AstroCanvas documentation

Install AstroCanvas and make your first visual edit.

AstroCanvas installs as a local Astro integration. It appears in Astro’s development toolbar, edits explicitly marked literal text and never adds the editor or write endpoint to a production build.

Get AstroCanvas for £5/monthTry the demo first

Using an AI coding agent? Grab thecopyable install instructions for AI agents.

1. Download the paid package

After purchase, use the licence key from the AstroCanvas email on the subscriber download page to downloadastrocanvas-astro-0.1.0.tgz. Place the archive in the Astro project. The package does not need to be unpacked manually.

2. Install the local archive

npm install ./astrocanvas-astro-0.1.0.tgz

Commit the resulting package manifest and lockfile changes according to the project’s normal dependency policy. Do not commit the downloaded archive if the repository is public or shared with people who are not covered by the licence.

3. Activate your licence

Copy the licence key from the AstroCanvas purchase email and activate it once on the developer machine. The key is stored outside the Astro project, so the same activation covers unlimited local projects.

npx astrocanvas activate

Paste the key when prompted. It is stored with user-only permissions outside project repositories. A subscription supports up to three developer-machine activations. Use npx astrocanvas deactivatebefore replacing a machine. AstroCanvas validates the subscription periodically and allows a seven-day grace period when the licence service is temporarily unreachable.

4. Add the Astro integration

Import AstroCanvas in astro.config.mjs and add it to the integrations array:

import { defineConfig } from "astro/config";
import astroCanvas from "@astrocanvas/astro";

export default defineConfig({
  integrations: [astroCanvas()],
});

5. Mark literal text

Add a unique data-astrocanvas value to text that should be editable. Use a stable, descriptive ID that will still make sense after the wording changes.

<h1 data-astrocanvas="hero-heading">
  A clear page heading.
</h1>

The first release supports literal text. Dynamic expressions, nested markup and duplicate IDs remain read-only because they cannot be replaced safely as one source string.

6. Open the editor

Run the project’s Astro development command, open the local site and choose AstroCanvas from the bottom dev toolbar. Activate selection mode, then click marked text on the page. The floating editor shows the source target and lets you preview replacement copy before saving.

7. Save and review

Saving makes one atomic change to the original .astro file. Review the Git diff and run the normal build or test command before committing. If AstroCanvas cannot locate one unique, safe literal target, it reports the problem and leaves the source unchanged.

Production behaviour

AstroCanvas registers only during local development. A production Astro build contains neither the visual toolbar app nor the source-writing endpoint. The finished website remains a normal Astro deployment.

Updates and support

AstroCanvas tells you in the dev-server terminal when a newer version is available. Update in place with:

npx astrocanvas update

That fetches the latest licensed package into the project and installs it with your package manager (add --download-only to fetch without installing). You can also re-download it by hand from the subscriber download page. Updating never alters existing source content. For installation problems, emailsupport@roughton.co with the Astro version and the relevant error message.

New to the workflow? Read the Astro visual editing guide orlearn when source-first editing is a good CMS alternative.