Comparison and Decision Guide

Drupal core is the framework and a minimal installation profile. Drupal CMS is a curated distribution of Drupal 11 that is assembled from recipes (a recipe is a package of configuration and dependencies applied once; see Recipes). It is not a fork: it is core plus contributed projects plus a pre-configured experience. Version 2.x makes Canvas the default editor and offers the site templates Byte, Starter (with the Mercury theme) and Blank, with an optional AI Assistant. Version 1.x is unsupported, and the documentation lives at project.pages.drupalcode.org/drupal_cms. Recipes have no update path: once applied, the site is an ordinary Drupal site, and you maintain it with Composer and Drush like any other. See Drupal CMS and Site Templates.

Rule of thumb. Choose Drupal CMS when a small team wants a good-looking, editor-friendly site quickly and has no strong opinion about the architecture. Choose core when the data model is the product, as with the museum’s collection, or when the project must pass a review of every installed module. The museum starts from core because it has a custom content entity and a curated roles model; a smaller museum partner site could start from a Drupal CMS template.

These three address the same editorial wish, a page that is more than one text field, in different ways.

Drupal CMS 2.0 had no automatic migration from Layout Builder or Paragraphs content to Canvas, so choose with the next three years in mind and re-check the Canvas release notes before planning a migration. Layout Builder stays in core. The older books Drupal 10 Masterclass (2023) and Drupal 10 Development Cookbook (2023) present Layout Builder as the only visual builder; since Canvas, it is one of three options, and the right default depends on who edits the page.

Rule of thumb. Use Paragraphs when the content is structured and repeated, Layout Builder when a few page types need bespoke layout and you want to stay on core, and Canvas when non-developers assemble varied pages from a component library. The museum uses structured content types and Views for exhibitions and objects, and Canvas for its home and campaign pages, with the ticket-banner code component.

A contributed module is maintained by the community and reviewed by the Security Team when it has a stable release that opts in to security coverage. A custom module is code your team owns forever.

Check before adopting a contributed project: the project page’s supported Drupal versions, its security-coverage badge, the date of its last release, its open issue queue, and whether it is the replacement for a module that was removed from core (see Removed Core Modules). Prefer a small contributed module and a small custom module over a large custom module that reimplements it. Whatever you write, follow Module Anatomy and the coding standards. Add Composer packages with composer require drupal/<project>, never by uploading code: module and theme upload from the UI was removed in 11.0 and 11.1.

Three places can hold the museum’s data.

The museum models exhibitions and events as node bundles, because editors, Content Moderation, Views and the front end expect them. It models the collection as a custom content entity, collection_object, with fields such as accession_number and period, because thousands of objects have their own list, access rules and import from a collection-management system, and do not belong in the editorial content list. A table of sync timestamps for that import is a custom table or state, since nobody edits it.

Rule of thumb. Start with a node bundle. Move to a custom entity when you need your own permissions, routes, storage or bulk lifecycle. Use a custom table only for data that will never need fields, translations or Views. See Content Types and Fields, Custom Entity Types and Database API and Entity Queries. Entity queries must call accessCheck() explicitly, whichever of the first two you choose.

All three expose content to other programs. JSON:API is part of core and needs no configuration; the core REST module (with Serialization) is also in core and exposes resources you enable one by one; GraphQL (5.x) is a contributed module. Simple OAuth (6.x) is contributed too, and 6 removed the implicit and password grants.

JSON:API follows the standard format with Drupal’s conventions, and business operations such as account creation, login and password requests are outside its scope. Because it exposes entities directly, bugs in the Entity, Field or Typed Data APIs can become security problems, so keep Drupal updated and use read-only mode where the front end only reads.

Rule of thumb. Default to JSON:API for the kiosk, because it needs no code and the museum’s gallery pages are read-mostly. Reach for REST only for a hand-shaped endpoint or an existing consumer. Add GraphQL when the client team needs to ask for deeply nested data in one round trip and agrees to maintain a schema. See JSON:API, REST and Serialization and GraphQL.

Since Drupal 10.0, Starterkit (php core/scripts/drupal generate-theme) is the way to start a theme: it copies a snapshot of the starter theme into your project, and it stays yours. A subtheme declares a base theme and inherits templates and libraries, which are updated when the base theme updates. Classy and Stable were removed in 10.0, and Stable 9 was deprecated in 11.4. Olivero, Claro and Stable 9 leave core in Drupal 12, and Default Admin, based on Gin, becomes the admin theme, so a theme that extends one of them as a base is the riskiest choice.

Rule of thumb. Generate a Starterkit theme for a custom site theme. Use a subtheme only when you intend to track a maintained base and accept its updates. See Starterkit and Subthemes.

Configuration management exports the site’s configuration to YAML. Environments still differ (a dev-only module, a different email address, a disabled cache), and there are two ways to handle that.

Source: Config Split project page

Rule of thumb. Use settings overrides for a few scalar values and for anything secret, and use Config Split when whole objects or module lists differ. Do not use both to control the same value. See Configuration Management and settings.php and Environments.

Drupal can serve several sites from one codebase, each with its own sites/<name> directory, settings and database (see Multisite).

Rule of thumb. Choose separate installs, usually with containers (see Docker and Containers), unless the sites truly share code, release cadence and a team, such as a museum with a main site and satellite sites that differ only in theme and content. Multilingual needs, such as the museum’s English and Spanish site, are not a reason for multisite: use one site with translations, see Multilingual.

A traditional Drupal site renders pages with Twig and the render system. A decoupled (headless) site uses Drupal as a content and API back end, and a separate front end, for example Next.js, renders the pages. Progressive decoupling sits between: Drupal renders the page and a JavaScript application owns a part of it.

Rule of thumb. Stay traditional unless you need more than one front end or the front-end team will not work in Twig. The museum keeps its public site traditional and uses a decoupled Next.js app only for the gallery kiosk. See Decoupled Drupal with Next.js and Authentication and OAuth.

Drupal pays back its learning curve when a site has structured content, roles, workflows, multilingual content and a long life. It is a poor fit in these cases.