@drupal-canvas/headless-next

Next.js adapter for the Drupal Canvas Headless SDK.

It gives a Next.js app draft preview bound to the editing user, in-place session renewal inside the Canvas editor frame, and the component metadata endpoint Drupal Canvas registers the app's components from.

Installation

npm install @drupal-canvas/headless-next

Set the CANVAS_SITE_URL environment variable to your Drupal site URL.

Usage

1. next.config.ts — the config wrapper generates the component manifest at build time, adds the SDK packages to transpilePackages, and sends a session-aware CSP frame-ancestors header:

import { withCanvas } from '@drupal-canvas/headless-next/config';

export default withCanvas();

2. Route files — mount the handlers, one file per route:

// app/api/draft/route.ts
import { createDraftRouteHandlers } from '@drupal-canvas/headless-next';

export const GET = createDraftRouteHandlers().draft.GET;

// app/api/draft/renew/route.ts
import { createDraftRouteHandlers } from '@drupal-canvas/headless-next';

export const POST = createDraftRouteHandlers().draftRenew.POST;

// app/api/disable-draft/route.ts
import { createDraftRouteHandlers } from '@drupal-canvas/headless-next';

export const POST = createDraftRouteHandlers().disableDraft.POST;

// app/api/canvas/components/route.ts
import { createComponentMetadataHandler } from '@drupal-canvas/headless-next';

export const runtime = 'nodejs';
export const dynamic = 'force-dynamic';
export const { GET, OPTIONS } = createComponentMetadataHandler();

3. Session banner — a server component gathers the session state (getDraftData(), getDraftEditorOrigin(), isDraftSessionExpired()) and renders <DraftSession> from @drupal-canvas/headless-next/client with a render prop that owns the banner markup.

4. Component tree — pass the structured content returned by fetchPage() to <CanvasComponentTree>:

import { CanvasComponentTree } from '@drupal-canvas/headless-next/CanvasComponentTree';

<CanvasComponentTree tree={page.content} />;

withCanvas() generates a registry of every discovered component implementation, and the renderer consumes it automatically. During development the registry updates when components are added, removed, or renamed.

Data access

getClient() returns the draft-aware JSON:API client; fetchPage() fetches rendered content, resolved through Drupal's routing. Both are draft-session-aware.