Drupal CMS and Site Templates

This content was generated with the assistance of AI and should be verified against the official Drupal documentation before being relied on in production.

This sub-section’s Drupal bibliography lists the reference material consulted while preparing these pages.

Drupal CMS is the packaged, opinionated way to start a Drupal 11 site. It is not a fork and not a different product: it is a Composer project that pulls in Drupal core and a curated set of contributed modules, themes and recipes, and an installer that applies the recipes you pick. Once the installer has finished, the result is an ordinary Drupal site. This page explains what the distribution contains, how its 2.x line is organised, how to install it, how its add-ons and AI tools work, what "no update path" means for recipes, and how to decide between Drupal CMS and a plain core project.

Facts on this page were checked against the official Drupal CMS documentation and release notes on 2026-10-30. At that date the newest stable Drupal CMS release is 2.2.7 (published on 2026-10-23), built on Drupal 11. The rest of this sub-section is written against Drupal 11.4.x, Drush 13/14 and PHP 8.3 or later; Drupal CMS follows the Drupal 11 line, so the same PHP and database baselines apply (see Requirements and hosting). The examples use the fictitious Meridian Museum site introduced in the sub-section index.

What Drupal CMS is (and is not)

Drupal core is deliberately small. A fresh core install gives you the content, user, field, views and theme systems, but, since Drupal 11.4, not even the Article and Page content types, and no media library configuration, SEO tools, consent management or visual page builder. A site builder has to choose and configure all of that. Drupal CMS packages one set of such choices, aimed at marketers, content creators and site builders:

A Composer project (drupal/cms) that requires Drupal core, the recommended contributed projects and a pinned set of recipes. The project template has the same shape as core’s recommended-project: a web/ docroot, a vendor/ directory and a composer.json you own.
Recipes. Each capability (SEO basics, accessibility tools, consent management, analytics, search, forms, the multilingual setup, the AI tools) is a Drupal recipe: a directory with a recipe.yml that installs modules, imports configuration and optionally creates content. Recipes are a core feature, available since Drupal 10.3 and stable enough to be the delivery mechanism of the distribution.
An installer. A short web wizard replaces the standard Drupal installer (see The setup wizard).
Defaults for editors. A dashboard with "Top tasks", the Gin administration theme, the Project Browser for installing more projects from the admin UI, Drupal Canvas as the editing experience and, optionally, AI tools.

What it is not: a fork of core, a hosted service or a separate release train for core code. Security fixes for Drupal core arrive through the normal Drupal core releases (see Versions, release cycle and support); Drupal CMS releases mostly move the set of recipes, templates and tested constraints. Its 1.x line is unsupported, so new work starts on 2.x, and the documentation moved from drupal.org pages to project.pages.drupalcode.org/drupal_cms. Links to older www.drupal.org/docs/drupal-cms pages redirect there.

Drupal CMS 2.x

Drupal CMS 2.0 was announced on 2026-01-28 on top of Drupal core 11.3. The minor releases that followed added the features that matter for planning:

Release What changed (from the release notes)

Release	What changed (from the release notes)
2.0	Drupal Canvas becomes the default editing experience; the Mercury component library; the first site template, Byte; optional AI tools (page generation from prompts, an administration chatbot, AI-assisted alt text, an AI dashboard).
2.0.1	The Blank site template is added: Drupal CMS features and Canvas with a blank theme based on core’s starter kit.
2.1.0	First-class support for free and premium site templates; the installer gains a template selection step; `drush site:export` and the Blank template can export an existing site as a recipe (a site template); default DDEV configuration and a generic `AGENTS.md` ship with the project.
2.1.1 to 2.1.6	Installer and `site:export` fixes (configuration is exported outside the web root by default); a raised minimum core version for security hardening in 2.1.2; Mercury improvements.
2.2.0	Multilingual support, a searchable language picker in the installer, translatable recipes and translatable Canvas pages. The core of the distribution moves into the `drupal_cms_site_template_base` recipe, which a site template adds to receive the recommended setup and upstream fixes. DDEV 1.25.0 or later is required.
2.2.4 and 2.2.5	Starter, Blank and the add-on recipes are removed from the default Composer dependencies, so a third-party site template cannot conflict with them; an experimental `drush site:archive` command; the installer no longer appends to `default.settings.php`; telemetry is on by default and no longer reveals names of custom modules and recipes.
2.2.7	Bug fixes and telemetry changes (the current stable release).

2.0

Drupal Canvas becomes the default editing experience; the Mercury component library; the first site template, Byte; optional AI tools (page generation from prompts, an administration chatbot, AI-assisted alt text, an AI dashboard).

2.0.1

The Blank site template is added: Drupal CMS features and Canvas with a blank theme based on core’s starter kit.

2.1.0

First-class support for free and premium site templates; the installer gains a template selection step; drush site:export and the Blank template can export an existing site as a recipe (a site template); default DDEV configuration and a generic AGENTS.md ship with the project.

2.1.1 to 2.1.6

Installer and site:export fixes (configuration is exported outside the web root by default); a raised minimum core version for security hardening in 2.1.2; Mercury improvements.

2.2.0

Multilingual support, a searchable language picker in the installer, translatable recipes and translatable Canvas pages. The core of the distribution moves into the drupal_cms_site_template_base recipe, which a site template adds to receive the recommended setup and upstream fixes. DDEV 1.25.0 or later is required.

2.2.4 and 2.2.5

Starter, Blank and the add-on recipes are removed from the default Composer dependencies, so a third-party site template cannot conflict with them; an experimental drush site:archive command; the installer no longer appends to default.settings.php; telemetry is on by default and no longer reveals names of custom modules and recipes.

2.2.7

Bug fixes and telemetry changes (the current stable release).

The 2.1 line requires PHP 8.3 or later, and each minor raises the minimum core version when a core security hardening needs it, so read the release notes of the version you install rather than assuming a fixed core number.

Drupal Canvas as the default editor

Drupal Canvas (formerly Experience Builder) is a contributed module, not part of core. Drupal CMS 2.x enables it so that an editor builds a page by dragging components onto a live preview instead of filling in admin forms. Components come from Single Directory Components in the active theme (see Single Directory Components) and from Canvas code components written in JavaScript and CSS. The Canvas module itself is covered in Canvas visual page building. Two consequences for a Drupal CMS site:

Core’s Layout Builder is still available, but the distribution’s templates are built for Canvas. Drupal CMS 2.0 had no automatic migration from Layout Builder or Paragraphs content to Canvas pages, so a site that already uses those tools keeps them or migrates by hand. See Layout Builder for the core alternative.
Canvas requires Drupal 11.3 or later, which is one reason Drupal CMS 2.x starts from 11.3.

The site templates

A site template is a recipe that describes a whole site: content types, fields, views, menus, a theme and often demo content. The installer applies the template you pick on top of the shared base recipe. Release 2.1 opened the format to third parties, so free and premium templates also appear in the installer. The templates that Drupal CMS names itself are:

Template Purpose Theme and design

Template	Purpose	Theme and design
Byte	A preconfigured marketing site for a SaaS product: blog, newsletter sign-up, pricing pages and a contact form, built with Canvas.	The `byte_theme` theme, a dark design, integrated with Canvas through Single Directory Components.
Starter	The least pre-built option, "a plain foundation you build up yourself": the Drupal CMS features without a particular vertical.	The Mercury theme and component library (`themes/contrib/mercury`), with cards, heroes, testimonials, menus and accordions available in Canvas.
Blank	A blank slate that keeps Drupal CMS features and Canvas but ships no demo content or opinionated design.	A theme named `blank`, generated from core’s starter kit; rename it by generating a new theme from it rather than by renaming the folder, because the name appears in several places.

Byte

A preconfigured marketing site for a SaaS product: blog, newsletter sign-up, pricing pages and a contact form, built with Canvas.

The byte_theme theme, a dark design, integrated with Canvas through Single Directory Components.

Starter

The least pre-built option, "a plain foundation you build up yourself": the Drupal CMS features without a particular vertical.

The Mercury theme and component library (themes/contrib/mercury), with cards, heroes, testimonials, menus and accordions available in Canvas.

Blank

A blank slate that keeps Drupal CMS features and Canvas but ships no demo content or opinionated design.

A theme named blank, generated from core’s starter kit; rename it by generating a new theme from it rather than by renaming the folder, because the name appears in several places.

The installer documentation also mentions further templates for non-profits, portfolios, schools and healthcare; a non-profit template named Haven appeared in 2.1. The page you read in a release’s notes is the authority on which templates ship in that release.

A template is only a starting point. Everything it creates is ordinary configuration and content, and you can change or delete it. For Meridian Museum, the Starter template is the natural base: it has no SaaS-specific content to remove, it already provides Canvas and Mercury, and the museum’s own meridian theme can replace Mercury later (see Starterkit and subthemes).

Installing Drupal CMS

There are three official routes, in the order the documentation presents them: the launcher for a trial, DDEV for local development, and a hosting provider for the live site.

The launcher

The Drupal CMS launcher is a standalone desktop application for Mac and Windows that runs Drupal CMS locally without installing anything else. You download the file for your operating system from the Drupal CMS site (a short form is involved), open it, and press "Visit site" to reach the setup wizard. A folder icon opens the site files and a trash icon resets the site by deleting its database. Things to know before relying on it:

It is a trial and evaluation tool, not a production environment.
It uses a SQLite database, which most hosting providers do not offer, so a site you intend to move to hosting should be built under DDEV instead.
You can still add modules, themes and recipes.
A launcher downloaded before Drupal CMS 2.0 must be deleted and downloaded again to get 2.0.

DDEV and Composer

For anything you plan to keep, use DDEV and Composer. DDEV runs the web server, PHP and database in containers and includes Composer, so nothing else needs to be installed (on Windows, the documentation recommends WSL2 and assumes it). The project type is drupal11 and the docroot is web:

ddev --version
mkdir meridian-museum && cd meridian-museum
ddev config --project-type=drupal11 --docroot=web
ddev composer create-project drupal/cms
ddev launch

Source: Drupal CMS: Install with DDEV

ddev launch opens the installer in the browser; ddev status prints the local URL later; ddev stop shuts the project down without losing work, and ddev launch starts it again. Drupal CMS 2.1 ships a default DDEV configuration, so the ddev config step mainly confirms the type and docroot. The deeper treatment of DDEV, Composer and the project layout is in Installation with Composer and DDEV and Project layout and local development.

Without DDEV, the same composer create-project drupal/cms runs on any machine that meets Drupal’s requirements; you then provide a web server and database yourself. Do not run it in a directory you want to keep: create-project needs an empty target.

The setup wizard

The wizard has four screens:

Site name. Shown in the header of the default theme and changeable later.
Site template. Choose Byte, Starter, Blank or another template offered by your release. Templates other than Byte have different names and content from the examples in the documentation.
Account. Email address and password for the administrator account. Use a unique password from a password manager; never reuse one across sites.
Finish. After setup you land on the Dashboard, whose "Top tasks" widget guides the first steps.

The toolbar of a new Drupal CMS site groups work into Pages, Media, Trash, Structure, Appearance, Extend, Configuration, People and Reports, with a keyboard shortcut (Alt+D on Windows, Option+D on Mac) to search the administration pages. Site-wide settings (site name, the site email address, the home page, error pages, performance settings) live under Configuration at /admin/config.

Add-ons

An add-on is a recipe the Drupal CMS maintainers recommend for the templates that fit it. They are installed from the administration UI, not from the command line:

Open Extend > Recommended (/admin/modules/browse/recommended).
Press Install on each add-on you want.
Answer the questions it asks, such as an API key or an analytics identifier.

Installing an add-on installs its modules and applies its configuration to the existing site; some add-ons also create demonstration content. Afterwards every setting is yours to change. Different templates recommend different add-ons. For more projects, Extend > Browse opens the Project Browser, which searches Drupal.org projects (modules and recipes), shows their project pages and installs them with the Install button. Behind the scenes the Package Manager runs Composer for you, which is why a hosting environment with a read-only codebase cannot use it; see Automatic Updates and Project Browser.

Since 2.2.4 the add-on recipes are not part of the default Composer dependencies. The Project Browser and the Recommended screen fetch them when you install them, and a project that needs them in composer.json (for example, to reproduce the site in CI) requires them explicitly.

The same mechanism works from the command line, which is how you apply recipes from a deployment pipeline (the recipes page covers the details):

ddev composer require drupal/example_recipe
ddev drush recipe ../recipes/example_recipe
ddev exec -d /var/www/html/web php core/scripts/drupal recipe ../recipes/example_recipe -v

Source: How to download and apply Drupal recipes

drush recipe needs Drush 13 or later, and the paths are relative to the web root. example_recipe stands in for a real project name.

The optional AI Assistant

Drupal CMS 2.x includes optional AI tools, installed as an add-on recipe. The AI Assistant helps users find features and configuration options, completes some site-building tasks and helps create content types, fields and categories; it also adds a button to generate alt text when an image is uploaded. To enable it:

Go to Extend > Recommended and press Install on the AI Assistant recipe.
Choose a provider and press Continue. The documented providers are amazee.ai, Anthropic and OpenAI.
Enter the API key if the provider needs one. amazee.ai requires none and includes a limited free trial that can be extended by registering; Anthropic and OpenAI are paid services, and a ChatGPT subscription key does not work.
Clear the cache if needed. An AI Assistant button appears in the top toolbar and opens the chat sidebar.

Security and operations points: keep the provider key out of the repository by supplying it through the environment or the Key module’s environment provider (see settings.php and environments); remember that prompts and uploaded images are sent to a third party, which belongs in your privacy policy; and give the assistant’s permissions only to trusted roles, because it can change site configuration. Exposing site data to external AI agents is a separate topic, covered in MCP Server and AI agents.

Recipes have no update path

This is the most important idea for operating a Drupal CMS site. A module is installed once and then updated through Composer and update.php. A recipe is different: when it is applied, its recipe.yml installs the listed modules and themes, imports its configuration and creates its content, and then it is finished. Drupal records no "recipe installed" state, a recipe cannot be uninstalled, and a newer version of the recipe is not diffed against your site. Drupal’s own Drupal CMS project page puts the consequence bluntly: asked how you update Drupal CMS, it answers that you do not, because it is a starting point for creating new sites.

In practice:

Core and contributed projects keep updating normally. The modules and themes that a recipe installed are Composer packages. composer update, security advisories and Automatic Updates (patch-level core updates) apply to them like to any other package. See Updates, Composer and security advisories.
Configuration that a recipe created is yours. A new Drupal CMS release can change the recipe’s configuration, but it does not change yours. To adopt an improvement, read the release notes and edit your configuration by hand, or export it and let configuration management carry it between environments (see Configuration management).
Re-applying a recipe is not an update. Applying again can overwrite configuration you changed or fail on conflicts. Treat it as an installation of a feature you do not yet have.
The recipe packages that remain in composer.json are Composer dependencies, not a runtime link. What the recipes created lives in your database and configuration; check what each package still provides before removing it.

After the installer finishes, a Drupal CMS site is "standard Drupal": no runtime code of Drupal CMS is needed for the site to function, and you can manage it with exactly the workflow of any other Drupal 11 site (Composer, Drush, configuration management, a deployment pipeline). The differences are what the installer left behind: the module set, the configuration and the default theme.

Drupal CMS or core `recommended-project`?

flowchart TD S[New Drupal 11 site] --> Q1{Editors need a visual page builder,<br/>SEO, consent and accessibility tools quickly?} Q1 -- yes --> Q2{A site template matches the<br/>project or a blank slate is enough?} Q2 -- yes --> CMS[Start from Drupal CMS] Q2 -- no --> CORE[Start from drupal/recommended-project] Q1 -- no --> Q3{Highly custom entities, strict dependency control,<br/>or an existing module set?} Q3 -- yes --> CORE Q3 -- no --> CMS CMS --> OPS[Same Composer, Drush and config workflow afterwards] CORE --> OPS

Start from Drupal CMS when the team wants a working, editor-friendly site in minutes, when a template is close to the goal, when the people building the site are site builders rather than module developers, or when the Canvas editing experience is a requirement. Start from core drupal/recommended-project when you need to control exactly which modules exist, when the site is an application built mostly from custom entities and code, when you are following a tutorial or an enterprise standard that assumes a minimal core, or when a Drupal CMS-specific default (for example the Gin theme, Package Manager or the telemetry) conflicts with your hosting policy.

The core project is created with Composer in the same way:

ddev config --project-type=drupal11 --docroot=web
ddev composer create-project drupal/recommended-project:^11 .
ddev composer require drush/drush

Source: Installing Drupal

The two are not exclusive: you can start from core and apply the Drupal CMS recipes you want (the add-ons are recipes), or start from Drupal CMS and later remove what you do not need. For the Meridian Museum, a team that mainly wants editors to build exhibition pages starts from Drupal CMS and the Starter template; the meridian_collection module and the meridian_events recipe are added on top without caring which route created the project. Note that the legacy drupal/legacy-project template is abandoned since Drupal 11.4, so it is not an alternative.

Common errors and pitfalls

DDEV version. Drupal CMS 2.2 requires DDEV 1.25.0 or later; an older DDEV fails in ddev launch or in the project configuration. Update DDEV first.
Wrong project type or docroot. Use drupal11 and web. A php or drupal10 type produces a site that cannot find its docroot or uses incompatible defaults.
Treating the launcher as the development environment. Its SQLite database and temporary nature make it a trial tool.
Expecting upgrades of the distribution. There is no "upgrade Drupal CMS 1.x to 2.x" operation for recipe-created configuration; 1.x is unsupported and a site on it is updated as ordinary Drupal.
Template names in old tutorials. Posts from before 2.0 describe a distribution without Canvas, site templates or the launcher’s current form.
Applying recipes on a production site without a backup. Recipes change configuration and content immediately; apply them in a branch, export the configuration and deploy it.
Assuming Starter and Blank are always in composer.json. From 2.2.4 they are no longer default dependencies; scripts that expect them must require them.
Provider keys in settings.php or in Git. Use environment variables.

Version notes and corrections of the books

Older books such as Drupal 10 Masterclass (2023) present recipes, Project Browser and Automatic Updates as future initiatives and Drupal CMS as not yet existing. Recipes are in core since Drupal 10.3, and Drupal CMS has been released since the 1.0 line, with 2.0 following on 2026-01-28. Drupal 10 Development Cookbook (2023) installs core with Composer and DDEV and never mentions Drupal CMS or Canvas; its Composer and DDEV workflow remains valid, but the Layout Builder-centred editing chapters apply to a core site and not to the Canvas-based templates. Drupal 10 itself ends on 2026-12-09, so a new site starts on Drupal 11 with either route. See also Where older books and tutorials are outdated and Comparison and decision guide.