Decoupled Drupal with Next.js

On the DDEV project from Installation with Composer and DDEV:

Source: Decoupled Drupal: APIs and useful modules

jsonapi is a core module that needs no configuration: it exposes every content entity type (and the configuration entities that opt in) under /jsonapi. The consumers module (a dependency of Simple OAuth) stores the OAuth clients. JSON:API Extras is optional; it lets a site rename resources and fields, disable resources it does not want to expose, and set a path prefix. Prefer fewer, deliberate customisations: every rename is a place where front-end code and back-end configuration can drift apart.

The matching DDEV configuration, with the Next.js application running on the host (or in a second DDEV project) and the Drupal site on its own hostname:

Source: DDEV: Config options

With this file the site answers on https://meridian-cms.ddev.site, which the Next.js project reads from NEXT_PUBLIC_DRUPAL_BASE_URL.

JSON:API accepts only read requests unless an administrator turns that off. The setting is "Accept only JSON:API read operations" on /admin/config/services/jsonapi, stored as read_only: true in jsonapi.settings. A read-only kiosk should keep it. If the front end creates or updates content (a visitor guestbook, for example), switch it off and protect each write with OAuth scopes and permissions, never with anonymous access. The related behaviour of anonymous requests is part of JSON:API.

Source: JSON:API module documentation

The exhibition content type becomes the resource type node--exhibition, served at /jsonapi/node/exhibition; the topic and gallery vocabularies become taxonomy_term--topic and taxonomy_term--gallery; the media types become media--image, media--document and media--remote_video. The custom content entity collection_object from Custom Entity Types has no bundles, so it becomes collection_object--collection_object at /jsonapi/collection_object/collection_object, with the fields accession_number, period, material, dimensions and on_display as attributes.

Source: JSON:API: Filtering

Four JSON:API habits matter for a front end:

Because JSON:API responses are cacheable and carry cache metadata, they work well with the layers described in Render API and Cache Metadata. Also consider the alternatives: a GraphQL schema when clients need very tailored queries (see GraphQL) and the core REST resources for single-purpose endpoints (see REST and Serialization).

Published content of the museum is public, so the build and the visitors need no credentials. A token is needed only for what anonymous visitors cannot see: unpublished drafts, and any write operation. Simple OAuth’s client credentials grant fits that server-to-server case: the Next.js server holds a client ID and secret for a dedicated Drupal user with a narrow role, and exchanges them at /oauth/token for a short-lived bearer token. The steps are:

Source: Next-Drupal: Environment Variables

The variable names above are the ones the next-drupal documentation uses. NEXT_PUBLIC_DRUPAL_BASE_URL is exposed to the browser by design (it is only a URL), while the other three must stay server-only. The OAuth background is in Client credentials and client authentication; the Drupal specifics (scopes, consumers, refresh tokens) are in Authentication and OAuth. Anonymous cookie-less requests to JSON:API must never carry a session: a bearer token on a request does not need CSRF tokens, but a cookie-authenticated write does.

Server-side fetches ignore CORS. A browser script on https://www.meridian.example calling https://cms.meridian.example/jsonapi/... does need it. Drupal core handles CORS through the cors.config container parameter, which is off by default:

Source: Decoupled menus: API usage (cross-domain access)

List exact origins; do not use '*' on an API that serves authenticated data, and keep supportsCredentials: false unless the browser really sends cookies. The general CORS mechanism is explained in CORS. A reverse proxy or CDN in front of Drupal must forward the Origin header and the Vary: Origin response header, or a cached response for one origin is served to another.

The Decoupled Router project page describes the module as an endpoint that takes a front-end path and tries to resolve it to an entity, following redirects and URL aliases as needed, and returning information about the route and the underlying entity. The endpoint is /router/translate-path with a path query parameter:

Source: Decoupled Router project page

A typical resolved response has these parts (shortened):

Source: Decoupled Router project page

The UUID and the jsonapi.resourceName are all the front end needs to request the full resource, and isHomePath lets it render the home page for /. When the requested path is a redirect (the Redirect module, or an old alias), the response describes the destination and the front end can answer with an HTTP redirect (redirect() from next/navigation or permanentRedirect()) so crawlers update their index; the exact redirect keys in the response should be checked against the installed version, because the 2.0.x releases changed redirect-loop and query-string handling.

Pitfalls:

The next-drupal documentation builds dynamic pages with generateStaticParams (using getResourceCollectionPathSegments), translatePath and getResourceByPath. The following page combines the documented client methods into a catch-all route for the museum (TypeScript, Next.js App Router):

Source: Next-Drupal: Building pages

The Next.js side of this file (async params, draftMode(), notFound()) is explained in Dynamic Routes and Route Groups and Data Fetching. resourceVersion: "rel:latest-version" is the JSON:API revisions parameter; it returns the newest revision (a draft in the moderation workflow) rather than the default published one, and only to a caller who holds the permissions to view latest versions (see Content Moderation, Workflows and Revisions).

The client itself is created once:

Source: Next-Drupal: Authentication

The NextDrupal class is for the App Router and NextDrupalPages for the Pages Router, according to the client introduction. The documented authentication options are bearer (OAuth), basic and Auth.js sessions, plus custom functions; use bearer in production and never basic with the shared admin account.

Navigation is editor data (see Menus and Path Aliases), so a headless front end must read it from Drupal instead of hard-coding links. Drupal’s decoupled-menus initiative produced a menu linkset endpoint. According to the decoupled menus documentation it is part of core as of Drupal 10.1.0 (earlier versions use composer require 'drupal/decoupled_menus:^1.0@beta'), whereas the JSON:API Menu Items project page says that Drupal 10.2 and later include a core linkset endpoint; check the release notes of the version in use, and on Drupal 11.4 the feature is available. It is switched on in the site settings under Web services, at /admin/config/services/linkset (the configuration key is linkset_endpoint).

Once enabled, the menu with machine name main is served at /system/menu/main/linkset, and a language prefix returns the translated menu (/es/system/menu/main/linkset). The endpoint respects user permissions, so anonymous callers see only what they may see, and administrative menus need an authenticated user. If the front end is on another domain and the browser fetches the menu, enable CORS.

Source: Decoupled menus: API usage

The response follows the IETF linkset draft. It contains a linkset array with an anchor and a flat item list; each item has href, title, hierarchy and machine-name. The hierarchy array gives the position of the link in the menu tree as index strings, so a top-level link has one index and its children add more; the front end rebuilds the tree from it. The excerpt below is shortened and the exact hierarchy values depend on the menu (the endpoint output of the installed version is the reference):

Source: Decoupled menus overview

Verification checklist for a menu: request the endpoint anonymously and as an editor, with and without a language prefix; confirm that disabled links and links to unpublished content are absent for anonymous callers; confirm that href values are front-end paths (or rewrite them; see below); change a title in the UI and confirm the response changes after the caches were invalidated.

Source: Decoupled menus: API usage

The function assumes that the hierarchy indexes are positions among siblings, which is how the documentation describes them; if the installed version numbers them differently, sort the items by hierarchy first. Menu links that point at content come out with Drupal-side URLs; if the back end lives on its own hostname, strip the base URL so <Link> (see Linking and Navigation) stays inside the Next.js site.

drupal/jsonapi_menu_items serves /jsonapi/menu_items/{menu} and presents menu links as menu link content entities, so it adds fields found only on those entities (such as UUIDs), covers menu_link_content and menu_link_config items, and is documented as compatible with the next-drupal tooling. Use the core linkset endpoint when a pure menu structure is enough and the JSON:API Menu Items module when links must be related to other resources. Because the latter is minimally maintained, prefer the core endpoint for a new project.

Source: JSON:API Menu Items

Every JSON:API response is a cacheable response with cache tags (node:12, node_list, file:5, config:...) that Drupal invalidates when the entities change. To see them in responses during development, turn on cacheability debug headers (the X-Drupal-Cache-Tags response header) in services.yml:

Source: Cache API: Cache tags

Use them to learn which tags a request depends on, not as a production contract: a front end that stores raw Drupal tags must also be told when a tag is invalidated, and Drupal does not emit that event to outside systems by default. Cache metadata in general is explained in Render API and Cache Metadata. A proxy such as Varnish or a CDN that purges by tag is configured separately (Performance and Caching).

The Next.js App Router can refresh content by time (next: { revalidate: 3600 }), by tag (next: { tags: [...] } plus revalidateTag) or by path (revalidatePath). The next-drupal documentation shows the time-based and tag-based forms with the native fetch. The full model, including the Next.js 16 signatures such as revalidateTag(tag, "max") and the Cache Components rules, is in Caching and Incremental Static Regeneration. For public museum data the front end fetches with the native fetch and attaches tags that Drupal can compute from the entity alone:

Source: Next-Drupal: Building pages

The time-based revalidate is the safety net; the tag is the precise path. Every collection fetch carries the tag of its resource type, so one invalidation of jsonapi:collection_object--collection_object refreshes every list that shows objects. For single resources add jsonapi:uuid:<uuid>.

Source: Next-Drupal: Revalidator

The secret travels in a header, not in the query string, so it does not end up in access logs. Use a POST because the operation changes state. The same endpoint can be called by the drupal/next module’s own revalidator plugins: the module documents a Path revalidator that refreshes a site based on the entity’s path, selected for each entity type on /admin/config/services/next/entity-types under On-demand Revalidation. The documentation of the revalidators describes the Drupal side only (custom plugins extend RevalidatorBase and implement revalidate(EntityActionEvent $event): bool; configurable ones extend ConfigurableRevalidatorBase), so the receiving Route Handler and its request format must match what the configured revalidator sends; set the secret in the Next.js site entry and in DRUPAL_REVALIDATE_SECRET. Revalidation runs at shutdown, so debug output from the plugin does not appear in the page response.

When the built-in path revalidator is not enough (a change to one object must refresh the kiosk list, the exhibition pages that reference it and the home page teaser), the module meridian_collection can send tags itself. It uses the object-oriented hooks of Drupal 11.1 and later (see Hooks and OOP Hooks):

Source: Change record: Support for object oriented hook implementations

The endpoint and secret come from settings.php, which reads the environment (see settings.php and Environments):

Source: default.settings.php (Drupal 11.x)

Design notes and pitfalls:

Menus, taxonomy terms, media and referenced entities all produce stale parents. Keep a map of "this change refreshes that tag" instead of relying on a clever generic rule; the tests in the kiosk section assert exactly that.

Modernizing Drupal 10 Theme Development (2023) builds its decoupled example with next-drupal on the Pages Router: getStaticProps, getStaticPaths and the 1.x DrupalClient. That code still describes a working configuration, but for new work the client class is NextDrupal for the App Router, the preview mechanism is Draft Mode (rather than the older Preview Mode and preview URL generators of next-drupal 1.5), and cache invalidation is tag-based. The Pages Router page of this site, Pages Router, explains the equivalent legacy concepts. Drupal’s own documentation now has a decoupled section, with JSON:API in core since 8.7, the Decoupled Menus initiative and Canvas support for decoupled front ends. For the full list of outdated advice, see Where Older Books and Tutorials Are Outdated.

Source: Canvas: Headless

The requirements are Drupal 11.3+ with Canvas installed; the canvas_headless submodule, which pulls in simple_oauth (6.1.0 or later), consumers and custom_elements; a Simple OAuth RSA key pair configured at /admin/config/people/simple_oauth (the same key pair signs preview assertions); the restricted permissions Administer Canvas Headless frontends and Access Canvas Headless preview, granted per role; Node.js 22.19+ or 24.5+ (Node 23 is not supported); and a Chromium-based browser for plain HTTP (Firefox needs HTTPS, and Safari needs CHIPS support).

Source: Canvas: Headless setup

The --site-url option writes CANVAS_SITE_URL into .env; the documentation states that this is the only configuration needed and that there is no client secret, because the application never stores a standing credential. For Next.js the template wires withCanvas() in next.config.ts and adds four route files under app/api/; every template provides a catch-all route, draft session routes, the /api/canvas/components endpoint and sample components. A 401 from the last curl is the correct answer: it means the route exists and rejects calls without a credential (WWW-Authenticate: Bearer and a missing_assertion error); the adapter also sends a frame-ancestors header that blocks embedding until a live preview session is active.

Then register the application in the Canvas editor: open Headless frontends from the icon rail, choose Add frontend and enter the dev server URL without a trailing slash, query or fragment. The browser probes each application and shows Ready (it responds like a Canvas adapter), Setup needed (something responds that is not an adapter) or Unreachable. Canvas previews through the first application in the list; the setting applies site-wide. Click Edit on a page, and the preview renders through the application, including unpublished content.

A component is defined in the front-end repository, and Canvas registers what the components endpoint advertises:

Source: Canvas: Headless setup

machineName is the identity of the component (the scaffold writes hello-world as a placeholder, so change it), status: true makes it available for placement (the scaffold sets false), and the target folder comes from componentDir in canvas.config.json. External components cannot be renamed or have their status changed in Drupal, and changing machineName later creates a new component while the old one remains on existing pages. Props defined in component.yml appear in the editor’s side panel.

The preview flow, as documented: the editor opens a page, the Canvas editor embeds the application, the application’s draft route exchanges a single-use assertion for an access token at Drupal’s /oauth/token, and the token is tied to the editor’s account and capped at a read-only preview scope. Listings and detail queries can still use JSON:API through the same client.

Canvas in Drupal CMS 2.x is the default editor, but no automatic migration from Layout Builder or Paragraphs to Canvas existed in Drupal CMS 2.0, so existing layouts need an explicit plan (Layout Builder, Drupal CMS and Site Templates).

The back end needs these ingredients, all built in other pages of this sub-section:

JSON:API does not return image styles by itself. Either add the contributed image-style resources, expose the style URL through a computed field in a normaliser, or let the front end use next/image with the original file and a loader that requests Drupal’s derivative URLs (the ?itok= token protects derivative generation; see Images, Fonts and Scripts for remotePatterns, which must list the Drupal host).

Source: Next-Drupal: Environment Variables

The page is a Server Component that loads the first screen, and a small Client Component that refreshes the list while the kiosk is on:

Source: JSON:API: Filtering

URLSearchParams percent-encodes the brackets, which JSON:API accepts. Rendering details of Server and Client Components are covered in Server and Client Components. The live refresh runs in the browser against the Drupal origin, so it needs the CORS configuration shown earlier; as an alternative, add a Route Handler on the Next.js side that proxies the request (the backend-for-frontend pattern in Route Handlers and Backend for Frontend) and no CORS is required at all, and the Drupal host never needs to be public to kiosks.

Check each layer in order. Every command must be run by the person building the site and compared with the expected output.

Source: Decoupled Router project page

The second command in step 1 should return a 4xx (read-only mode, or access denied), the first request of step 4 a 401, the unknown path of step 2 a 404, and the revalidation response should list "revalidated": true. A Drupal Kernel or Functional test can assert the same API contract on the back end (see Automated Testing), and a Playwright test the end-to-end behaviour of the front end (see End-to-End Testing).