Static delivery

Static delivery adds CaretCMS to a static Astro site without running CMS routes in production. Editors use inline editing and Studio in astro dev. During astro build, CaretCMS writes published content into the generated HTML.

When to use it

Use static delivery when…	Use server delivery when…
Your site ships as static files (Netlify, Vercel static, S3, CDN)	You already run Astro with output: 'server'
Publish → rebuild → deploy is acceptable for public updates	You need visitor-visible edits immediately after save
You want CaretCMS without an SSR adapter	You want per-request HTML rewriting in production

How it works

1. Edit locally      /admin and Studio run in astro dev
2. Save draft        Work remains private to the editor
3. Publish           Content is written to shared storage/source files
4. Build             Astro generates HTML using that published content
5. Deploy            Visitors receive the new static files

Your template markup supplies the default content. Until an editor saves an override, visitors see the original HTML. After publish and rebuild, stored values replace tagged fields in the built files.

With markdownStorage(), supported prose edits publish back into the source .md file before CI rebuilds it. Every drafted range is rechecked first; a stale_body or invalid_body conflict leaves that entry’s source and draft untouched instead of triggering a partial publish.

Setup

1. Wire the integration

   astro.config.mjs

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

   npx @caretcms/caretize init scaffolds this automatically for static Astro projects.

2. Make content editable

   Add data-caret attributes by hand or run npx @caretcms/caretize. Existing .md content collections are stamped automatically for supported prose when Markdown storage is active. See Inline editing and Markdown body editing.

3. Author locally

   npm run dev

   Sign in at /admin. With no CARET_EDIT_PASSWORD set, a temporary dev password prints in the terminal.

4. Publish, build and deploy

   Publish the saved draft from the editor first. A build reads shared published content, not private drafts. Make that content available in the build checkout.

   npm run build

   Look for [caretcms] static delivery bake complete (N/N HTML files rewritten). Deploy dist/ to your static host — no CMS routes in production output.

Publish webhook (optional)

astro.config.mjs

caret({
  delivery: {
    mode: 'static',
    bake: true,
    publish: {
      webhookUrl: process.env.CARET_REBUILD_WEBHOOK_URL,
      method: 'POST',
      headers: { authorization: `Bearer ${process.env.CI_TOKEN}` },
    },
  },
})

After Publish, the webhook receives:

{
  "source": "caretcms",
  "event": "publish",
  "published": [{ "collection": "pages", "id": "home", "revision": 3, "deleted": false }],
  "commit": "abc123..."
}

A webhook failure does not undo published content. Use Retry deploy to retry the rebuild request without publishing again. HTTP acceptance is not proof of deployment completion: see Deployment status. Publication can also have per-entry conflicts or recovery failures; review Publish recovery before interpreting a success response.

Getting published content into CI

CI (your automated build service) needs the content before it builds. A rebuild webhook does not upload your local files. CI must receive the published Markdown/JSON or read the same supported storage. For a git workflow, commit and push the content before rebuilding; CARET_GIT_ON_PUBLISH attempts a local commit but does not push. Keep private drafts out of the published repository.

Configuration reference

Option	Default (static)	Notes
delivery: 'static'	—	Shorthand for { mode: 'static', bake: true }
delivery.mode	'auto' if omitted	Resolves to static when Astro output is static; set 'static' to enforce this path
delivery.bake	true when mode is static	Set false to skip HTML rewrite at build
delivery.publish.webhookUrl	none	Called after successful publish
delivery.publish.method	POST	POST or PUT
delivery.publish.headers	{}	Extra headers for the webhook
delivery.publish.timeoutMs	5000	Request timeout, bounded to 1–30000 ms

See Configuration for all caret() options.

Troubleshooting

Choosing automatic or explicit delivery

caret() defaults to delivery: 'auto' and detects Astro static output. Use delivery: 'static' explicitly to document the choice. Older CLI versions may still recommend the explicit setting.

Edits work in dev but not on the deployed site

You likely deployed without a post-publish rebuild, or CI could not read storage (.caret/data/ missing from the build environment). Run astro build locally and confirm the bake log line.

Build log says bake skipped

Ensure a storage provider is configured (default filesystemStorage() is fine) and delivery.bake is not false.

Next steps

Caretize CLIAuto-tag templates from existing markup.

QuickstartInstall, edit, publish, and preview.

DeploymentStorage, CI, and host matrix.

ConfigurationFull caret() reference.