--- title: "Drupal Canvas AI Builder" date: "2026-07-02T13:30:48+00:00" summary: "Build Drupal Canvas assets for Acquia Source CMS using AI coding agents. Set up local codebases, sync with GitHub, and preview with Workbench." image: type: "page" url: "/acquia-source/drupal-canvas-ai-builder" id: "99e30b5a-974f-4dcf-96f7-2b9f644623aa" --- Table of contents will be added 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](https://react.dev) styled with [Tailwind CSS](https://tailwindcss.com/), and pages, content templates, and global regions as  [json-render](https://json-render.dev) 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 ----------------------------------------- **Phase** **Category** **Task** **Description** **Phase 1:**  **Getting started and setup** Setup and workflow  (Choose path A or path B) Path A:  GitHub Sync setup (Recommended) Recommended workflow. Uses GitHub as the source of truth.  Connect a GitHub repository, clone it, install dependencies, create a `.env` file, and login.     GitHub Sync workflow Pull changes, work in editor/agent, commit/push, and allow synchronization.     Path B:  Manual CLI setup (Advanced) Advanced workflow. Allows direct publishing without Github.  Access site, add API client, store secret, select scopes, and save. Create project, select template and AI agent.  Copy `.env.example` to .`env`, set URL and credentials.     Manual CLI workflow Pull latest changes, work locally, and push changes. **Phase 2:**  **Building with the agent** Local development AI agent setup Open the project in the AI coding agent. Seed the project by copying example directories.     Local preview Run `npm run dev` to start Drupal Canvas Workbench and visually verify components iteratively during the build.   Generation inputs  (Choose one or more sources) Input sources Instruct the agent on which source is authoritative when combining multiple inputs.     Build from live URL Optional input method for visual baselines. Provide public URL and run build/QA prompt.     Build from Figma Optional input method using design context. Use Figma MCP to provide design context and run build/QA prompt.   Remote Configuration Configure navigation Enable Source MCP, get connection details, connect to AI agent, and request menu inspection. 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. Note For optimal results, use the Blank or Default site templates. 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](https://docs.acquia.com/acquia-source/github-sync). 2. Run the following command in the local terminal to clone the connected repository:  git clone git@github.com:/.git 3. Run the following commands to install dependencies:  cd  npm install 4. Create a `.env` file with the following content:  CANVAS_SITE_URL=https://.cms.acquia.site CANVAS_JSONAPI_PREFIX=api 5. Run the following command to authenticate with Source CMS:  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. Important Do not run `npx canvas push` from this local codebase. Allow the GitHub synchronization process to publish repository changes to Source CMS.  Use `npx canvas pull` only when the repository requires the current Source CMS state. For example, run the command before enabling synchronization for pages, content templates, or global regions that were previously excluded from synchronization. This prevents the GitHub synchronization from treating missing local files as deletions when it next updates Source CMS. 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](https://docs.acquia.com/node/69836#access-a-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.  Note Do not use the anonymous user. The selected user appears as the author of client-driven changes, but the selected OAuth scopes control authorization. 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: 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:  cd cp .env.example .env 17. Set the Source CMS URL and API client credentials in the .env file with the following configuration:  CANVAS_SITE_URL=https://.cms.acquia.site CANVAS_CLIENT_ID= CANVAS_CLIENT_SECRET= CANVAS_JSONAPI_PREFIX=api Note Acquia Source CMS requires C`ANVAS_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: 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: 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](https://project.pages.drupalcode.org/canvas/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:  npm run dev 2. Open [http://localhost:5173](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 , , and patterns from . 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 `` with the public URL you want to use as a design reference: Build Drupal Canvas Code Components, page specs, and region specs from . 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](https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server). 2. Use the following example prompt:  Build Drupal Canvas Code Components, page specs, and region specs from . 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](https://docs.acquia.com/acquia-source/acquia-source-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:  Use Source MCP to add menu links for the new pages