@batterai/strapi-plugin-canvas

Installable Strapi 5 plugin for same-origin Canvas authoring.

The admin bundle mounts @batterai/editor-shell directly inside the Strapi admin SPA. Browser calls go through Strapi admin routes and useFetchClient; the package does not import the public render adapter or iframe a dev server.

Minimal Config

export default () => ({
  canvas: {
    enabled: true,
    config: {
      licenseKey: process.env.BATTERAI_CANVAS_LICENSE_KEY,
    },
  },
});

Unlicensed production authoring remains usable with a watermark. Localhost authoring is exempt.

Editor appearance and CMS themes

Canvas inherits its editor chrome colors from Strapi's active Design System theme. This means a project's config.theme.light and config.theme.dark customizations also follow Strapi's user-selected light/dark mode inside Canvas.

For Canvas-specific colors, register an appearance from the Strapi admin customization entrypoint. Use a resolver when light and dark need different values; it receives the currently active Strapi theme and is reevaluated when the CMS theme changes.

// src/admin/app.tsx
import { registerCanvasAppearance } from "@batterai/strapi-plugin-canvas/strapi-admin";

export default {
  register() {
    registerCanvasAppearance((theme) => ({
      accent: theme.colors?.primary600 as string,
      accentStrong: theme.colors?.primary700 as string,
      selection: theme.colors?.primary600 as string,
    }));
  },
};

Supported keys are accent, accentStrong, accentSoft, background, border, borderSubtle, ink, muted, mutedDisabled, panel, panelStrong, and selection. Values must be six-digit hex colors. Canvas applies them as namespaced --be-editor-* custom properties; selection defaults to the blue accent. These tokens style authoring chrome only and are separate from persisted website content.

Register Your Web Component Packages

Canvas includes its built-in block packages. Register additional approved BlockPackage modules from the host app's admin customization file, inside register():

// src/admin/app.tsx
import { registerCanvasBlockPackages } from "@batterai/strapi-plugin-canvas/strapi-admin";
import { acmeBlockPackages } from "./canvas/blocks";

export default {
  register() {
    registerCanvasBlockPackages(acmeBlockPackages);
  },
};

Every package supplies one versioned custom element, its server render path, and block-owned stylesheet URLs. Register packages before the Canvas page mounts (Strapi's register() phase); duplicate block types fail immediately. Each source block belongs in its own folder with block.ts or block.tsx and block.css.

Seed Library

seedLibrary provides the block palette (categories/blocks/presets) written into the plugin's canvas-site document when that document is FIRST created. It is first-creation-only seed data, not a live source: an existing site document's library is never overwritten by config changes — after the first boot the palette lives in Strapi and evolves through the editor (for example saved presets).

// config/plugins.js
module.exports = ({ env }) => ({
  canvas: {
    enabled: true,
    config: {
      licenseKey: env("BATTERAI_CANVAS_LICENSE_KEY"),
      seedLibrary: require("./canvas-library.json"),
    },
  },
});

The value is an object with optional categories, blocks, and presets arrays (any missing key seeds as empty). Block entries need at least type and label; every seeded type must have an installed BlockPackage.

Public Delivery

The plugin exposes a read-only content API route for the visitor website:

GET /api/canvas/delivery

Use it as the SSR host delivery source:

PUBLIC_SITE_DELIVERY_URL=https://cms.example.com/api/canvas/delivery bun run public-site

The delivery route returns published Canvas pages plus published bound collections. Draft/editor data remains behind Strapi admin routes.

Proof

bun run test:strapi-plugin-canvas
bun run strapi-plugin:fresh-install
bun run strapi-plugin:fresh-install:live