Drupal Headless Code Components Setup - My First Attempt

Overview

This is an overview of my first attempt at working with Drupal Code Components and headless Next.js. The purpose of this page is to document my poor understanding of how to set this up so that I may revisit it when I know better and so that I may mentor other people to do better.

See https://project.pages.drupalcode.org/canvas/headless/setup/ for the offical documentation.

Outline of Setup Steps

  • Create a folder for the project and cd into it.
  • Configure DDEV for Drupal with some extra modules needed for the Canvas Headless (canvas_headless) module
  • Create a folder to store OAuth keys.
  • Enable the Canvas Headless and the Canvas OAuth modules
  • Log in with Chrome (the docs say you have to use a Chromium-based browser, so no Firefox of Safari..)
  • Scaffold the Canvas Headless code, in a new folder called headless, with support for Next.js
  • Get Vercel AI agent skills to help your agents understand the Next/React conventions.
  • Get Drupal Canvas AI agent skills
  • Install Canvas CLI
  • Start the Canvas Headless Next.js server.
  • Initialize a git repo with a default .gitignore
  • Generate OAuth keys
  • Setup a consumer
  • Add the Frontend in the Canvas editor
  • Login with Canvas CLI
  • Push the default Code Components to Drupal
  • Edit a page in the Canvas editor in Drupal
  • View the site in the Next.js app in the browser

Detailed Setup Steps

cd ~/Sites
mkdir headless
cd headless


ddev config --project-type=drupal11 --docroot=web
ddev start

ddev composer create-project drupal/recommended-project
ddev composer require --dev 'drush/drush'
ddev composer require 'drupal/canvas' 'drupal/consumers' 'drupal/custom_elements' 'drupal/simple_oauth'

ddev restart

mkdir keys
ddev drush si -y
ddev drush en canvas_headless, canvas_oauth -y
open -a "Google Chrome" "$(ddev drush uli)"

npx @drupal-canvas/create@latest headless \
  --template nextjs \
  --site-url https://headless.ddev.site \
  --agents none

cd headless
npx skills add vercel-labs/agent-skills --yes
npx skills add drupal-canvas/skills --yes
npm install @drupal-canvas/cli
npm run dev

Open up a new terminal window.

  • Remove the newly added .git folder that the scaffolding added (~/Sites/headless/headless/.git).
  • Init a git repo for the whole project instead.
  • Make an initial commit so that later, you can get a clear picture of what Canvas CLI creates or pulls in.
rm -rf ~/Sites/headless/headless/.git
cd ~/Sites/headless/
git init .
echo "web/sites/default/files" >> .gitignore
echo "vendor" >> .gitignore
git add . && git commit -m 'initial commit'

Open http://headless.ddev.site/admin/config/people/simple_oauth and click "Generate keys" button, then enter the folder that was created in the steps above:

/var/www/html/keys

Make sure to click the "Save configuration" button.

Open http://headless.ddev.site/admin/config/services/consumer and click "+ Add Consumer", then set the following field values:

  • Label: Code Components
  • Client ID: code-components
  • Grant types (enable both):
    • JWT bearer (preview assertion)
    • Authorization Code
  • Authorization Code settings
    • Enable all scopes
    • Enable "Automatic authorization", "Remember previous approval", "Use PKCE?"
    • Redirect URIs:
http://localhost:4444/callback
  • Disable "Is this consumer 3rd party?"
  • Disable "Is Confidential?"
  • Set "Access token expiration time" to 86400 (one day)
  • Click Save
  • Open http://headless.ddev.site/admin/content/pages and click "Add Page", which opens up a new Canvas editing screen at canvas/editor/canvas_page/1
  • Click the icon in the left rail for "Headless frontends"
  • Click "Add frontend".
    • For the Frontend URL field, use the following (no trailing slash, no query, and no fragment):
http://localhost:3000

If everything went as expected, the "Frontends" section will show http://localhost:3000 as being "Ready".

Change the default OS browser to Chrome; the Canvas CLI login command will open a browser and it needs to be Chrome (or Chromium-based).

  • Cd into the headless folder in the directory of the site.
    • In this example, the site and the folder are both named headless.
  • Login with Canvas CLI using the OAuth consumer client id from the step above (code-components).
cd ~/Sites/headless/headless
npx canvas login --client-id code-components

That will open a browser window to a link on the Drupal site, which redirects you to a localhost page that shows you a success/failure message. If everything went well, you can now use Canvas CLI (npx canvas) to push and pull components between Drupal and Next. Since the scaffolding created some new components, use the push command to get them to the Drupal site:

npx canvas push

Now, you can create a page in Drupal and the components from the Next.js app should appear there. Build out a page, change some css in the code if you want (headless/app/globals.css for example, maybe change the body background color), and watch things change in the edit screen in realtime. Then, save your changes in Canvas, just like when you are in regular non-headless mode, and view your site at http://localhost:3000.

Notes

The example above doesn't use Astro, but if you do use Astro:

npx astro telemetry disable
Tags
Drupal