Migration from Drupal

We start by separating two decisions that are often conflated: (1) where content is authored and governed, and (2) how experiences are composed and delivered. A headless approach typically centralizes authoring in a CMS and delivers structured content via APIs to multiple channels. A composable approach goes further by decomposing capabilities (search, personalization, forms, DAM, experimentation) into independently owned services. The decision is driven by operating model and integration complexity. If the primary goal is decoupled frontend delivery with a stable content backbone, headless is often sufficient. If multiple teams need to own different capabilities with independent roadmaps and procurement, composable can be a better fit, but it requires stronger governance around contracts, observability, and change management. We document target-state responsibilities (CMS vs frontend vs integration layer), define API contracts, and validate the approach against non-functional requirements such as preview, caching, localization, and editorial workflow parity. The outcome is an architecture decision record that is testable against real content and delivery scenarios, not just diagrams.

Drupal features usually fall into three categories during migration: content modeling concerns, presentation concerns, and business logic concerns. Views and blocks often mix all three, so we decompose them into explicit responsibilities. For example, a View that lists content by taxonomy becomes a query capability in the API layer (filtering, sorting, pagination) plus a frontend rendering pattern. Blocks typically map to reusable content components or composition patterns in the target CMS. Custom modules are assessed for whether they implement business rules, integrations, or editorial workflow extensions. Business rules may move to an application service, integration layer, or serverless function depending on latency and security requirements. Workflow extensions may be replaced by native CMS capabilities or by external approval tooling. We avoid a one-to-one “rebuild everything” approach. Instead, we inventory each feature, define the target implementation pattern, and decide whether to replace, retire, or re-implement. This keeps the migration focused on platform evolution rather than recreating historical coupling.

We design for repeatable migration runs and, where required, incremental synchronization. The approach typically includes an initial bulk migration to establish the target dataset, followed by scheduled delta runs that capture changes made in Drupal while the new platform is being built and tested. To enable this, we use deterministic identifiers, track last-modified timestamps or change logs, and implement idempotent load behavior so reruns do not create duplicates. We also define a clear “source of truth” window: at some point close to cutover, content changes may be restricted to specific types or workflows to reduce divergence. Operationally, we align the plan with editorial calendars and release governance. The output is a cutover runbook that specifies when freezes apply (if any), what content can still change, how deltas are applied, and how verification is performed. This reduces the risk of a big-bang freeze while keeping data consistency manageable.

We treat migration code as production-grade software: versioned, testable, and runnable in controlled environments. A common setup includes containerized migration jobs (for example using Docker) with environment-specific configuration for source Drupal access, target CMS/API credentials, and logging destinations. We typically recommend at least three environments: development for pipeline iteration, staging for full-scale rehearsal with representative datasets, and production for cutover execution. Staging should mirror production constraints such as rate limits, API quotas, and network access. Tooling needs include: structured logging, metrics for throughput and failures, and artifact storage for reports (counts, validation summaries, redirect maps). Where possible, we integrate migration runs into CI/CD so reruns are consistent and auditable. The goal is to avoid one-off scripts executed from laptops and instead provide a repeatable operational process.

We map integrations by responsibility and data flow rather than by Drupal implementation. For search, we identify indexing sources, document structures, and update triggers. In a headless/composable model, indexing may be driven by CMS webhooks, scheduled jobs, or event streams, and the frontend may query search directly rather than via the CMS. For analytics, we focus on continuity of measurement: pageview semantics, route changes, campaign parameters, consent behavior, and key events. If URLs change, we plan mapping and reporting adjustments. For identity, we review authentication flows, session handling, and authorization boundaries, especially if Drupal previously handled both content and access control. The integration plan is validated end-to-end in staging: content changes propagate, search results match expectations, analytics events fire correctly, and identity constraints are enforced. This reduces surprises where the CMS migration is “done” but the platform is not operationally complete.

Yes, and it is often a pragmatic transition step. Drupal can act as a content source via REST or GraphQL while a Next.js frontend takes over routing, rendering, and performance responsibilities. This can reduce time-to-value by decoupling frontend delivery first, then migrating content and editorial workflows later. However, it requires clear contracts and constraints. You need stable API shapes, a strategy for previews, and agreement on which system owns routing and URL aliases. You also need to account for Drupal-specific behaviors that may not translate cleanly to API delivery, such as complex Views logic or block placement rules. We typically recommend defining a “strangler” boundary: which pages or sections move first, how caching is handled, and how SEO signals remain consistent. This approach can reduce risk, but it should still be managed as a staged migration with explicit milestones to avoid creating a long-lived hybrid that is hard to operate.

Post-migration governance is primarily about preventing schema drift and breaking changes for consumers. We recommend treating the content model and APIs as contracts with versioning rules, review gates, and automated checks. This includes naming conventions, required fields, localization rules, and relationship constraints. Operationally, we define ownership: who can change the model, who approves changes, and how changes are communicated to frontend and integration teams. For API delivery, we align on compatibility policies (for example, additive changes are allowed without coordination, but removals require deprecation windows). We also recommend maintaining a lightweight catalog of content types and their consumers, plus automated validation in CI for schema changes. The objective is to keep the platform evolvable without reintroducing the uncontrolled divergence that often accumulates in long-running Drupal estates.

We establish URL ownership as an explicit architectural decision: which system is authoritative for route generation and how legacy aliases are represented. In many migrations, the frontend becomes the routing authority, while the CMS provides slugs and structured fields used to compose routes. Redirects are treated as data, not ad-hoc configuration. We generate redirect maps from the legacy Drupal alias set, normalize patterns, and store them in a system that can be tested and deployed (for example, edge configuration, application middleware, or a dedicated redirect service). We also define rules for canonical URLs, trailing slashes, and parameter handling. Governance includes a change process: how new routes are introduced, how old routes are deprecated, and how teams validate that redirects remain correct over time. This reduces the risk of SEO regressions caused by uncoordinated routing changes after launch.

The most common risks are (1) incomplete parity requirements, (2) hidden coupling in Drupal implementations, (3) data quality issues, and (4) operational cutover gaps. Parity risk occurs when teams assume “content migration” is enough, but critical behaviors like permissions, previews, redirects, and search are not specified. We mitigate this by producing an inventory and acceptance criteria early, including a list of critical journeys and non-functional requirements. Hidden coupling is addressed through dependency analysis of modules, Views, blocks, and integrations, with explicit target patterns defined for each. Data quality risk is managed with validation at scale: counts, required fields, relationship integrity, and representative render checks. Operational risk is reduced with rehearsed cutover runbooks, incremental sync where needed, and rollback planning. The goal is to convert unknowns into testable artifacts before the launch window, not during it.

We address security and compliance across three areas: data handling, access control, and operational execution. For data handling, we classify content and user data, define what is migrated, and ensure extraction and storage follow retention and encryption requirements. Migration logs are designed to avoid leaking sensitive fields. For access control, we map Drupal roles and permissions to the target model. In headless/composable setups, authorization often shifts to an identity provider and API gateway or application layer. We define which APIs are public, which require authentication, and how tokens and secrets are managed across environments. Operationally, we use least-privilege credentials, segregated environments, and auditable CI/CD pipelines for migration jobs. We also include security review checkpoints for new endpoints, webhook configurations, and any data export mechanisms. This keeps modernization work aligned with enterprise security expectations rather than treating it as a one-time data move.

Timelines depend on estate size, integration complexity, and how much of the experience layer changes. As a reference, an enterprise migration usually includes: discovery and inventory (2–6 weeks), target architecture and content model design (3–8 weeks), pipeline implementation and iterative runs (4–12 weeks), frontend transition work in parallel (variable), and cutover rehearsal plus launch (2–6 weeks). The critical factor is parallelization. Content modeling, pipeline work, and frontend delivery can proceed concurrently once contracts are defined. Another factor is whether you need incremental sync and parallel run; this adds engineering effort but reduces freeze requirements. We plan the work around measurable milestones: inventory completeness, model sign-off, first full migration run, parity validation thresholds, redirect coverage, and cutover rehearsal success criteria. This provides predictable decision points for go/no-go rather than relying on a single end-date estimate.

Collaboration typically begins with a short discovery engagement focused on making the migration measurable and de-risked. We start by aligning stakeholders on goals (modernization drivers, target channels, editorial needs), then perform a structured inventory of the Drupal estate: content types, volumes, taxonomies, media, workflows, integrations, and URL patterns. From that, we produce a migration blueprint: target architecture options, recommended sequencing (what moves first), content model mapping approach, API contract outline, and an operational cutover plan including SEO continuity. We also identify key risks and the validation strategy needed to prove parity. The output is a scoped delivery plan with milestones and artifacts, plus a clear engagement model for how teams work together (roles, decision cadence, environments, and handover expectations). This ensures implementation starts with explicit contracts and acceptance criteria rather than assumptions carried over from the legacy Drupal build.