# Migrating classic Drupal sites to Drupal CMS Apply recipes to an existing Drupal 10/11 site. Keep Layout Builder pages and add Canvas only where it pays. - Date: 2026-07-28 - Category: Drupal A Drupal CMS migration is how I move a classic Drupal 10 or 11 site onto Drupal CMS's recipe-and-product layer without throwing away Layout Builder pages that already work. I am Alan Vo, a Gold Coast web developer with 18 years on CMS builds. In 2026 Drupal CMS is a product on core: installer, recipes, Project Browser, often Gin, SEO Tools, and Canvas on new templates. Your existing site is already core. The job is to apply what you need, keep what still sells (or informs), and add Canvas only where it pays. This note is for teams with a live Drupal 10/11 codebase who were told to "upgrade to Drupal CMS". Pair it with [Drupal CMS recipes](https://alanvo.com/blog/drupal-cms-recipes/) and [Drupal Canvas vs Layout Builder](https://alanvo.com/blog/drupal-canvas-vs-layout-builder/). The product overview lives at [Drupal CMS](https://new.drupal.org/drupal-cms). There is no magic migrator that turns a 2018 custom theme into Mercury plus Canvas overnight. ## Why a Drupal CMS migration is worth it now A Drupal CMS migration is worth it now when you want recipes, automatic update tooling Drupal CMS advertises, Project Browser for editors, and a path to Canvas without a second CMS. It is not worth it as a rebrand for a site that already runs Drupal 11, has a locked IA, and has no editor pain. Drupal CMS is not a new major version of your nodes. It is a packaged way to run core. I migrate when: - Editors cannot install a vetted add-on without a developer, and Project Browser plus recipes would reduce tickets. - You want the SEO Tools / privacy / media recipes as a baseline you can re-apply on the next site. - You are rebuilding the front theme onto SDCs anyway, so Canvas has somewhere to land. - Security and automatic updates policy matches what the organisation will actually run. I do not migrate when the only brief is "Drupal CMS is the new name on the keynote." A coffee shop brochure and a design-studio editorial site can stay on well-built Drupal 11. They can also take a light recipe apply (SEO Tools) without taking Canvas or a site template. Drupal 10 to 11 is a core upgrade. Drupal CMS is a product overlay. Do the core upgrade first if you are not on 11. Then talk recipes. Mixing a D10-to-D11 jump, a theme rewrite, and Canvas in one weekend is how you get an unbisectable outage. ![Drupal CMS migration documentation open beside a laptop](../../images/blog/drupal-cms-migration-1.jpg) ## How a Drupal CMS migration actually works A Drupal CMS migration actually works as Composer and config, not as an export-import of the whole CMS. You already have `composer.json`. Drupal CMS projects have a known package set and recipe folders. The practical paths are: 1. Light apply. Stay on your project template. Composer-require the recipes you want (`drupal_cms_seo_tools`, media, etc.). Apply on a clone. Export config. Keep your theme and Layout Builder. This is what I do most on living sites. 2. Rebase onto a Drupal CMS project template. New `composer.json` constraints, new recommended admin theme, Project Browser, maybe Automatic Updates. Higher risk. Do this when you want the full product and you have test coverage. 3. Greenfield CMS install plus content migrate. Only when the theme and IA are being thrown away. Migrate API for nodes, files, users. Rebuild layouts. This is a rebuild that happens to land on Drupal CMS. I almost always choose (1) for corporate and editorial sites with Layout Builder overrides. I add a `landing` bundle for Canvas later if the theme becomes component-based. Composer is the gate. Drupal CMS recipes expect module versions in a range. Your lockfile may pin an older Metatag. Resolve that on a branch. Do not apply a recipe against modules you cannot update. Config split (dev/stage/prod) still applies. Recipes should land in the split you use for all environments, then you export. Applying only on production UI is how staging drifts. Content stays. Node IDs stay. Path aliases stay if you do not let a recipe rewrite Pathauto. That is the point of additive recipes. The scare story is a recipe that recreates `page` and editors start using the new bundle. I hide extra bundles or I never apply that recipe. Layout Builder stays until you move a URL. I disable Canvas on bundles that have LB overrides. I enable Canvas on a new type. Hybrid is described in the Canvas note. The migration is the moment you write that rule down so it survives the next contractor. Admin UX: Gin is common on Drupal CMS. If editors know Seven or a custom admin theme, budget training. Do not surprise a museum comms team with a new admin chrome the same day you change Metatag. ## Drupal CMS migration production checklist 1. Inventory Drupal version, PHP version, Composer plugins, hosting (Pantheon, Acquia, Platform, custom). 2. Inventory layout systems: Layout Builder, Paragraphs, Panels leftovers, custom page entities. 3. Upgrade to a supported Drupal 11 core first if needed. Run tests. Then branch for CMS recipes. 4. Diff `composer.json` against a fresh Drupal CMS template. List modules you will take and modules you will not. 5. Require one recipe on a database clone (SEO Tools is the usual first). Apply. Export. Review the diff line by line. 6. Repeat for media and any privacy recipe legal signed off on. Stop before "all recipes". 7. Confirm Layout Builder view modes unchanged. Click five heavy pages. 8. Confirm cron, search index, sitemap, and redirects. 9. If you add Project Browser, lock who can install. Production module install still needs a change-control story. 10. If you add Canvas, new bundle only. Component theme required. No homepage cutover in the same deploy as Composer rebase. 11. Accessibility and performance pass on a recipe-touched admin path and on the front. 12. Document rollback: previous `composer.lock` plus database snapshot. Recipes are not always a clean uninstall. ![Team workshop around a table planning a CMS rebuild](../../images/blog/drupal-cms-migration-2.jpg) Haven-style brochure Drupal and studio editorial Drupal are small enough that a light apply is often enough. They are also small enough that a full rebase is tempting. I still take the light path unless the theme is already dead. ## What breaks during a Drupal CMS migration A Drupal CMS migration breaks when Composer constraints fight, when a recipe overwrites text formats, and when Canvas and Layout Builder both claim the homepage. Failure modes: - Automatic Updates or Project Browser installing a module that is not in git on the next deploy (deploy wipes it). Policy: code still ships through Composer in CI. - Gin vs custom admin CSS. Editors lose a button you had injected for a workflow. - Recipe enables a search backend you do not host. - PHP version on the host below what Drupal CMS 2.x expects. - Existing install profile hooks fighting recipe config (old distributions). - Multilingual config only applied in the default language. - "Uninstall Layout Builder" as a goal instead of a later phase. You will orphan layout_builder data. I keep a freeze branch of the pre-migration site for a release cycle. Rolling back Composer without the database is how you keep new nodes and lose the ability to edit them. Hosting is part of the migration even when the ticket says "just recipes". Drupal CMS 2.x may want a newer PHP than a brochure site has been running since 2022. Object cache, trusted host patterns, and reverse proxy headers do not change because the product name changed, but a new admin theme will hit more CSS on `/admin`. I test the editorial workflow on the staging host, not only on Lando. Cron on a small Annecy brochure site is cheap. Cron on a media-heavy studio archive after Simple XML Sitemap starts rebuilding is how you discover the recipe enabled a heavier sitemap than the old custom one. ![Library stacks used as a stand-in for structured content](../../images/blog/drupal-cms-migration-3.jpg) ## How to measure a Drupal CMS migration Measure a Drupal CMS migration with: core and module health (status report), editor ability to complete the same tasks, unchanged public HTML on Layout Builder URLs, and a recipe baseline you can reproduce on a new environment. If the homepage HTML hash changes when you only applied SEO Tools, you imported too much theme or block config. Diff. I also watch: - Time to spin up a new developer environment. Recipes should make that closer to the CMS installer story. - Number of Layout Builder pages still serving. That number should not drop unless you moved URLs on purpose. - Search Console coverage. A migration should not noindex the site because a recipe set a maintenance flag or a robots default. Do not claim a traffic lift from applying Drupal CMS. Claim a maintainable baseline. Traffic is content. ## Related work on this site Smaller Drupal sites are honest test beds for a light CMS migration because they still have real templates and editors. [Haven Coffee + Kitchen](https://alanvo.com/work/haven-coffee-kitchen/) is Drupal for a coffee shop and kitchen in Annecy: menu, galleries, jobs. [Studio Modular](https://alanvo.com/work/studio-modular/) is an editorial Drupal site for a graphic design studio. Both were contract development on an agency team. Those are not Canvas-everywhere rebuilds. They are candidates for recipes (SEO, media) on the Drupal they already have, Layout Builder or classic templates left intact, and Canvas only if a later brand site needs campaign pages. ## FAQ ### Is a Drupal CMS migration the same as upgrading to Drupal 11? A Drupal CMS migration is not the same as upgrading to Drupal 11. Drupal 11 is core. Drupal CMS is recipes, installer UX, and optional Canvas on top of core. Do core first if you are behind. Then apply product pieces. ### Will a Drupal CMS migration delete my Layout Builder pages? A Drupal CMS migration should not delete Layout Builder pages if you apply recipes additively and do not uninstall Layout Builder. Canvas is a separate enable. Keep LB on existing bundles until you rebuild those URLs on purpose. ![Government-style office desks and screens](../../images/blog/drupal-cms-migration-4.jpg) ### Can I run a Drupal CMS migration without Canvas? You can run a Drupal CMS migration without Canvas. Many sites only want recipes and admin UX. Canvas needs a component theme and a content plan. Skip it until both exist. ### When should I rebuild instead of a Drupal CMS migration? Rebuild instead of a Drupal CMS migration when the theme, IA, and layout system are all wrong, or when you are still on an old distribution you cannot Composer-reconcile. Then a new Drupal CMS install plus Migrate API is cleaner than fighting the profile. Brochure sites with a healthy D11 theme should not pay for a rebuild just to say CMS on the box. HTML version: https://alanvo.com/blog/drupal-cms-migration/