README

Canvas Component Manager is a Drupal module designed to streamline the management, deployment, and sharing of Canvas code components. It provides a graphical interface (UI) to export, import, audit, and version-control component configurations.

Features

Dashboard UI: A central hub to view all JS components, check their status, and perform bulk operations.
Revision Management: View change history, compare versions (Diff), and restore previous component states.
Usage Auditing: Integration with the Canvas Audit service to prevent accidental deletion of components currently in use by content or templates.
Default Content Integration: Seamlessly exports dependency components when exporting nodes via the Default Content UI module.
Smart Import: Automatically detects and imports components from ZIP archives.
Auto-Import: Automatically detects and imports components from the js_components directory of newly installed modules.
Format Support: Supports both CLI Source (component.yml + index.jsx) and Config Export (canvas.component.*.yml) formats.
Bulk Actions: Export or delete multiple components at once.
Auto-Cleanup: Automatically cleans up temporary export files via Cron to save disk space.

Installation

Via Composer (Recommended)

This method automatically installs required dependencies (like the Canvas module).

Run the command:

composer require drupal/canvas_component_manager

Enable the module:
```
drush en canvas_component_manager
```

Permissions

This module defines a single permission to restrict access to sensitive operations:

Administer Canvas Component Manager: Grants access to the overview page, import/export features, deletion, and settings.

Why two export types?

Canvas components are unique because they exist as both Configuration (Drupal entities with UUIDs) and Code (JavaScript/CSS). This module provides two export methods to handle different scenarios:

Source Export (UUID-Agnostic)
- What it is: A ZIP containing raw source files (index.jsx, component.yml).
- Best for: Sharing components between unrelated sites (e.g., from a Dev sandbox to a Client site).
- Why: It strips specific identifiers (UUIDs), forcing the target site to create a fresh instance of the component. This avoids ID conflicts.
Config Export (UUID-Preserving)
- What it is: A ZIP containing strict Drupal config files (canvas.component.js.*.yml).
- Best for: Deployments, Recipes, and CI/CD pipelines.
- Why: It preserves the exact UUIDs. When imported, Drupal knows it is updating the same component rather than creating a duplicate.

Usage

User Interface

Navigate to Configuration > Development > Canvas Components Overview (/admin/config/development/canvas_component_manager).

Overview: View a list of all Code (JS) components.
Revisions: Click "Revisions" on any component to view its history. You can "View Changes" (Diff) to see exactly what lines of code changed between versions, or "Restore" an older version.
Check Usage: Components that are "In use" display a link to a modal detailing where the component is used (Content, Templates, etc.).
Export: Select components and click "Export" to download a ZIP file.
Import: Use the "Import" tab to upload ZIP archives.
Settings: Configure your preferred default export format and integrations at the Settings tab.

Workflows

Moving Components Between Sites (Source Export)

Use the Export Source option when you want to copy a component from Site A to Site B.

Select the component(s) and click Export Source.
This generates a ZIP containing the raw CLI structure (component.yml, index.jsx, dist/).
Upload this ZIP to the target site using the Import tab.
Why: This format is "UUID-agnostic." It will create a fresh instance of the component on the new site, avoiding configuration conflicts.

Building Recipes & Deployments (Config Export)

Use the Export Config option when you are creating a Drupal Recipe, a Feature module, or deploying changes to a staging/production environment.

Select the component(s) and click Export Config.
This generates a ZIP containing strict Drupal configuration files (canvas.component.js.*.yml).
Extract these files into your Recipe's config folder or your module's config/install directory.
Why: This preserves the exact UUIDs and system properties, ensuring that updates are tracked correctly by Drupal's configuration management system.

Default Content UI Integration

This module integrates with Default Content UI to support "Ambitious Site Builder" workflows.

If you use Default Content UI to export content (e.g., a "Home Page" node or a "Landing Page" template), Canvas Component Manager will automatically:

Scan the content for any Canvas Code Components it uses.
Recursively find any components those components depend on.
Bundle all of them into the export automatically.

To enable this:

Go to Settings (/admin/config/development/canvas_component_manager/settings).
Ensure "Auto-export Canvas Code Components" is checked.
Select your preferred export format (Source or Config).

Notes for Developers

Auto-Importing in Custom Modules

To bundle components with a custom module (e.g., for distribution or recipes), place your component directories inside a js_components folder in your module's root.

Structure:

my_custom_module/
└── js_components/
    └── my_cool_component/
        ├── component.yml
        ├── index.jsx
        └── dist/
            ├── index.js
            └── index.css

When my_custom_module is installed, Canvas Component Manager will automatically scan this folder and import the components.

File Structure (Exports)

When exporting, the module generates standard YAML configuration files:

canvas.component.js.[id].yml: The component definition (props, slots, versioning).
canvas.js_component.[id].yml: The actual JavaScript code (original and compiled).

Importing Source Code

If you are importing raw source code (CLI format), ensure your ZIP archive includes the dist/ folder with compiled index.js and index.css files. If these are missing, the component may not render correctly until re-compiled via npx canvas build locally.

Requirements

Drupal Core: ^11.3
Canvas: The base Canvas module is required.

kevinfunk / canvas_component_manager

Maintainers

Package info

Statistics

Security