Skip to content
CaretCMS

Quickstart

Five steps. Five minutes. End state: a working Astro site where you can click on text and images to edit them.

This guide assumes you are adding CaretCMS to an existing Astro project. Greenfield? Clone examples/starter or examples/content-site from the repo and skip to step 4.

Prerequisites

Section titled “Prerequisites”
  • Node 20+ and npm 10+ (or pnpm 9+ / yarn 4+)
  • An existing Astro 5 or 6 project (or a blank npm create astro@latest)
  • Server output enabled — output: 'server' in your astro.config.mjs

Five-minute setup

Section titled “Five-minute setup”

  1. Install the package

    Terminal window
    npm install @caretcms/core

  2. Add the integration

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import caret from '@caretcms/core';
    

    export default defineConfig({
      output: 'server',
      integrations: [caret()],
    });

    Defaults give you admin UI at /admin, API at /api/cms, filesystem storage at .caret/data/, and local image uploads at public/uploads/. Customize in Configuration when ready.

  3. Annotate your template

    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".

  4. Set the editor password

    .env
    CARET_EDIT_PASSWORD=devpass
    CARET_SESSION_SECRET=replace-with-a-long-random-string
    Terminal window
    npm run dev

    Generate a real session secret:

    Terminal window
    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.

You also get:

Content Studio Structured editing for every collection at /admin/cms.

Where edits live

Section titled “Where edits live”

The default filesystem adapter writes JSON under .caret/data/:

  • Directory.caret/data/
    • Directorypages/
      • home.json created on first save
    • Directorysite/
      • global.json
  • Directory.caretcms/
    • revisions.json
    • Directoryhistory/
      • …
    • Directorycollections/
      • …

Collections and directories are auto-created on first write — no setup required. To git-track your content instead, point dataRoot at a folder inside src/ (see Storage Adapters).

Common gotchas

Section titled “Common gotchas”

For more, see Troubleshooting.

Next steps

Section titled “Next steps”
Inline Editing The full data-caret attribute reference.
Schemas Register Zod schemas for typed Studio fields.
Live Collections Query CMS data from astro:content.
Deployment Node, Vercel, Fly, Cloudflare Workers.