This guide explains how to set up a local codebase for an AI coding agent, such as Claude Code, Codex, or Cursor. The agent uses the codebase to build Drupal Canvas assets for Acquia Source Content Management System (CMS): Code Components as React components styled with Tailwind CSS, and pages, content templates, and global regions as  json-render specs.

This workflow uses the following tools and services:

• Source CMS: Serves as the destination site.
• GitHub repository: Stores and versions code. This is optional but strongly recommended.
• Local terminal: Runs Drupal Canvas Workbench for local preview. You can also run the coding agent in the terminal.
• AI coding agent: Uses the local codebase, tools, and agent skills to build Drupal Canvas assets.
• Code editor or IDE: Supports manual code changes when required.

Drupal Canvas AI Builder Workflow Summary

This guide explains how to set up a local codebase for an AI coding agent, such as Claude Code, Codex, or Cursor. The agent uses the codebase to build Drupal Canvas assets for Acquia Source Content Management System (CMS): Code Components as React components styled with Tailwind CSS, and pages, content templates, and global regions as  json-render specs.

This workflow uses the following tools and services:

• Source CMS: Serves as the destination site.
• GitHub repository: Stores and versions code. This is optional but strongly recommended.
• Local terminal: Runs Drupal Canvas Workbench for local preview. You can also run the coding agent in the terminal.
• AI coding agent: Uses the local codebase, tools, and agent skills to build Drupal Canvas assets.
• Code editor or IDE: Supports manual code changes when required.

Drupal Canvas AI Builder Workflow Summary

Prerequisites

• An Acquia Source CMS site is created and accessible. 
• Github is installed on the local computer.
• Node.js v20 or a later version is installed on the local computer.

Phase 1: Getting started and setup

Proper setup prepares the local environment and the Acquia Source CMS site for site building. The following sections outline the prerequisites, explain how to select an appropriate workflow, and provide instructions for establishing the codebase using either GitHub synchronization or the manual Canvas CLI.

Setup and workflows

Proper site configuration ensures compatibility with generated Drupal Canvas assets. It is recommended to create the Acquia Source CMS site from the Blank template. To obtain a larger set of starter components, use the Default site template.

Choosing a setup workflow

• Acquia Source GitHub bidirectional synchronization: (Recommended) Select this option to implement the recommended team workflow with GitHub as the source of truth. Commit and push to GitHub. Source CMS synchronizes the repository changes.
• Manual Drupal Canvas command-line tool (CLI) synchronization: (Advanced) Select this option to publish directly from a local codebase or when GitHub synchronization is absent. 

Acquia Source–GitHub sync 

This setup utilizes GitHub to manage version control and automatically synchronize select site configuration with Source CMS. The recommended workflow connects the Source CMS site to a GitHub repository. After connecting a repository, Source CMS prepares the Drupal Canvas project structure in that repository and keeps generated Drupal Canvas assets synchronized with version control. 

To configure the repository, do the following:

1. Connect a GitHub repository. For instructions, refer to GitHub sync.

2. Run the following command in the local terminal to clone the connected repository: 

   copy

   git clone [email protected]:<username-or-org>/<repository>.git

3. Run the following commands to install dependencies: 

   copy

   cd <repository> npm install

4. Create a .env file with the following content: 

   copy

   CANVAS_SITE_URL=https://<your-source-site>.cms.acquia.site CANVAS_JSONAPI_PREFIX=api

5. Run the following command to authenticate with Source CMS: 

   copy

   npx canvas login

Workflow with Acquia Source–GitHub sync

After configuring the repository, keep version control in sync by pushing local changes to GitHub rather than pushing directly to Source CMS.

To use GitHub as the source of truth for generated Drupal Canvas assets, do the following:

1. Pull the latest changes from the GitHub repository.
2. Work locally in a code editor or AI coding agent.
3. Commit and push changes to GitHub.
4. Source CMS synchronizes the pushed changes to the site.

Manual Drupal Canvas CLI synchronize

The manual synchronization workflow allows direct publishing of local codebase changes to Source CMS without relying on the build-in GitHub synchronization. Select this workflow to synchronize changes with Source CMS manually through Drupal Canvas CLI.

To create an API client for Drupal Canvas CLI authentication in Source CMS, do the following:

1. Access your site.
2. In the left sidebar, click API.
3. Select API clients or visit /admin/config/services/api-clients/.
4. Click + Add API client.
5. In the Label field, enter the API client label. 
6. In the Client ID field, enter your client ID.
7. In the New secret field, enter a client secret to create a hash of the secret key.
8. Store the client secret securely because it is required in .env.
9. In Grant types, select the Client Credentials checkbox.

The system displays the Client Credentials settings menu.

10. Select all scopes prefixed with canvas:.
11. In the User field, select a non-anonymous Source CMS user for client-credential actions. 

12. Click Save.
13. On your local machine, open the terminal.

14. In your local terminal, to scaffold a new codebase, run the following command:

    copy

    npx @drupal-canvas/create@latest

15. When prompted, do the following:
    1. Enter a project name.
    2. Select acquia/nebula as the template.
    3. Select the preferred AI coding agent or agents.

16. Run the following commands to open the generated project and copy the .env.example file to create a .env file: 

    copy

    cd <project-name>
    cp .env.example .env

17. Set the Source CMS URL and API client credentials in the .env file with the following configuration: 

    copy

    CANVAS_SITE_URL=https://<your-source-site>.cms.acquia.site
    CANVAS_CLIENT_ID=<client-id>
    CANVAS_CLIENT_SECRET=<client-secret>
    CANVAS_JSONAPI_PREFIX=api

Workflow with manual Drupal Canvas CLI synchronize

Use the Canvas CLI to manually push and pull assets when automated version control synchronization is not active.

Version control remains strongly recommended for this workflow, especially when multiple users work on the Drupal Canvas assets. The npx canvas pull command synchronizes Code Components. The command does not pull supporting imports unless they are also Code Components. Keep third-party dependencies, shared JavaScript modules, SVGs, images, and other supporting files in version control.

To synchronize Drupal Canvas assets between the local codebase and Source CMS with Drupal Canvas CLI, do the following:

1. On your local machine, open the terminal.

2. Run the following command before starting work, because Source CMS can have newer changes:

   copy

   Run npx canvas pull 

3. Work locally in a code editor or AI coding agent.

4. Run the following command to publish local changes to Source CMS:

   copy

   npx canvas push 

Phase 2: Building with the agent

Work with an AI coding agent

AI coding agents utilize specific skills and the local codebase to generate and edit Drupal Canvas assets. Both setups yield a local codebase connected to Source CMS. Open the project in the AI coding agent. The codebase includes agent skills in .agents/skills/ to create and edit Code Components, pages, content templates, and global regions.

You can start from the examples, or you can ask the agent to generate new assets.

To seed the project with examples, copy the following directories:

• Copy examples/components/ to src/components/.
• Copy examples/pages/ to pages/.
• Copy examples/regions/ to regions/.

The agent can add packages, shared code, SVGs, and other static assets from the local codebase. Use the Code Components imports and assets reference for supported import patterns. The repository also includes checks for the agent to run during development. 

Local preview with Drupal Canvas Workbench

Drupal Canvas Workbench provides a local environment to review changes before synchronization with Source CMS. Use Workbench to preview Code Components, pages, global regions, and content templates before synchronizing changes to Source CMS. You can also ask the AI coding agent to use Workbench to verify its changes against the local preview.

1. To start Drupal Canvas Workbench from the local terminal, run the following command: 

   copy

   npm run dev

2. Open http://localhost:5173. 

Input sources

AI coding agents require design references or structural context to accurately generate Drupal Canvas assets.

Your AI coding agent can use one or more references as input, including:

• Figma files or frames.
• Live URLs.
• Existing component libraries or codebases.
• Screenshots, copy, brand guidelines, or design tokens.

When using multiple inputs, specify which source is authoritative if the references conflict. Use the following example prompt:

Build Drupal Canvas Code Components, page specs, and region specs using <figma-url>, <url>, and patterns from <path-to-codebase>. Treat Figma as the source of truth for layout. Run local visual QA in Workbench.

Building from a live URL

Your AI coding agents can use a live website as a visual baseline to generate corresponding Drupal Canvas assets.

To build from a live website, do the following:

1. Open the agent harness.

2. Enter the following instruction, replacing <url> with the public URL you want to use as a design reference:

   copy

   Build Drupal Canvas Code Components, page specs, and region specs from <url>. Run local visual QA in Workbench.

After you submit the instruction, the agent inspects the URL, creates local Drupal Canvas assets, and verifies the result in Workbench.

Building from Figma

AI coding agents extract precise design contexts directly from Figma using the Figma MCP server. Figma MCP is useful when starting from a Figma file or URL. The server provides the agent with design context from Figma, such as frames, layers, and design tokens. 

1. Configure Figma MCP in the AI coding agent. For instructions, refer to the Figma MCP server guide.

2. Use the following example prompt: 

   copy

   Build Drupal Canvas Code Components, page specs, and region specs from <figma-url>. Run local visual QA in Workbench

Navigation menus

To manage site structure effectively, the AI coding agent modifies navigation menus directly on the remote Source CMS site. Source CMS provides an MCP server that the AI coding agent uses for menu and menu link work.

To configure and use the Source MCP for navigation menus, do the following:

1. Ensure that Source MCP is enabled on the Source CMS site.
2. Obtain the connection details at /admin/config/services/mcp. 
3. Connect the Source MCP as an HTTP MCP server in the AI coding agent.

4. Request the agent to inspect existing menus before making changes. 

   For example, use the following prompt: 

   copy

   Use Source MCP to add menu links for the new pages