Quickstart

This guide adds editable text and images to an Astro site in five steps.

Fastest path on an existing site

Run npx @caretcms/caretize init, then npx @caretcms/caretize. The first command installs and configures CaretCMS; the second adds bindings to templates. See Caretize CLI. The steps below show the manual setup.

This guide is for adding CaretCMS to an existing Astro project. Starting fresh? Clone examples/starter from the CaretCMS repo and skip to step 4.

Prerequisites

• Node 22.12+ and npm 10+ (or pnpm 9+ / yarn 4+)
• An existing Astro 6 or 7 project (or a blank npm create astro@latest)

Pick your delivery mode

Static site (recommended)

Keep Astro’s default static output. No SSR adapter. Public visitors see edits after Publish → rebuild → deploy.

Full guide: Static delivery.

Server-rendered site

Use output: 'server' plus an SSR adapter when you need edits visible to visitors immediately (per-request middleware rewrite).

Five-minute setup

1. Install the package

   npm

   npm install @caretcms/core

   pnpm

   pnpm add @caretcms/core

   yarn

   yarn add @caretcms/core

   Server delivery also needs an adapter, e.g. npm install @astrojs/node.

2. Add the integration

   Static delivery

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import caret from '@caretcms/core';
   
   export default defineConfig({
     integrations: [caret({ delivery: 'static' })],
   });

   Server delivery

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import node from '@astrojs/node';
   import caret from '@caretcms/core';
   
   export default defineConfig({
     output: 'server',
     adapter: node({ mode: 'standalone' }),
     integrations: [caret()],
   });

   Or run npx @caretcms/caretize init to install and wire CaretCMS automatically — then npx @caretcms/caretize to tag existing markup. See Caretize CLI.

   Defaults: admin at /admin, API at /api/cms, uploads at public/uploads/. Storage is filesystem (.caret/data/) unless CaretCMS detects Astro content collections under src/content/ — then it picks markdown storage automatically. See Storage adapters and Configuration.

3. Annotate your template

   By hand:

   src/pages/index.astro

   <main data-caret-scope="pages::home">
     <h1 data-caret="headline">Welcome to my site</h1>
     <p data-caret="intro">This text can be edited inline.</p>
     <img data-caret="hero" src="/img/hero.jpg" alt="" />
   </main>

   How the binding resolves:

   • data-caret-scope="pages::home" sets the collection (pages) and id (home) for everything inside.
   • Each data-caret="field" inside that scope binds to that field on the entry.
   • For images, the editor opens an upload dialog and rewrites src on save.

   You can also write the full binding inline without a scope: data-caret="pages::home::headline".

   Or scan an existing site with Caretize — it inserts bindings from your current markup.

   Tip

   The text in your template is the default. CaretCMS only overrides it once an editor saves a value. Until then your template renders as-is.

4. Set the editor password

   .env

   CARET_EDIT_PASSWORD=devpass
   CARET_SESSION_SECRET=replace-with-a-long-random-string

   npm

   npm run dev

   pnpm

   pnpm dev

   yarn

   yarn dev

   With no password configured, a temporary dev password is printed in the terminal (dev only).

   Generate a real session secret:

   node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

5. Edit

   1. Open http://localhost:4321/admin and log in with the password.
   2. Go back to your homepage.
   3. Click any annotated text — it becomes contenteditable. Hit Enter or click outside to save.
   4. Click an annotated image — an upload dialog opens. Pick a file; it uploads and the src updates.
   5. Reload — your edit persists.
   6. In dev, open Astro’s Dev Toolbar → CaretCMS to highlight every binding on the page (no login required).

You also get:

Content StudioStructured editing for every collection at /admin/cms.

Where edits live

Filesystem (default)

JSON under .caret/data/:

• Directory.caret/data/

  • Directorypages/

    • home.json created on first save
  • Directorysite/

    • global.json
• Directory.caretcms/

  • revisions.json
  • Directoryhistory/

    • …
  • Directorycollections/

    • …

Markdown (auto-detected)

When src/content/ has Astro collections, frontmatter and supported .md prose edits write to your files on Publish. Revisions still live in .caretcms/.

Collections and directories are created on first write. To git-track JSON content, point dataRoot at a folder inside src/ (see Storage Adapters).

Already have content collections?

If your content lives in Astro content collections (src/content/blog/*.md with a schema in content.config.ts), CaretCMS detects them automatically and uses the Markdown adapter — editing each entry’s frontmatter and supported prose in place, so the same files power both getCollection() and CaretCMS. No separate .caret/data/ store, and nothing to configure (set storage: filesystemStorage() if you’d rather opt out).

Common gotchas

Static site but no static delivery configured

If you have output: 'static' without caret({ delivery: 'static' }), the integration logs a warning and skips authoring routes. Add static delivery or switch to server output. See Static delivery or Troubleshooting.

Login works but click-to-edit doesn't

Make sure your page has a data-caret field or supported Markdown prose stamped with data-caret-md. The editor runtime only loads when an editable binding is present.

401 Unauthorized on save

Your session expired (12h TTL). Reload /admin and log in again.

403 with `Missing required request header`

A custom client is calling /api/cms/mutate without the x-caret-request: 1 CSRF header. Add it. The shipped editor does this automatically.

For more, see Troubleshooting.

Next steps

Caretize CLIAuto-tag an existing Astro site.

Static deliveryBake content into static HTML at build time.

Inline EditingThe full data-caret attribute reference.

SchemasRegister Zod schemas for typed Studio fields.

Live CollectionsQuery CMS data from astro:content.

DeploymentStatic CDN, Node, Cloudflare Workers.