Getting started

Mica adds an editing interface to an Astro project. The website keeps reading local files and builds to static output.

Mica is experimental and pre-1.0. Its API and content format can change. Use it for work that you can update as the project changes.

What you need

• Node 22.12 or newer
• An Astro 6 or 7 project
• A Git repository for the project

1. Install the packages

npm install @micacms/astro @micacms/core

2. Define a content model

Create src/mica.ts. The model is plain TypeScript and imports nothing from Astro.

import { collection, defineSite, richText, slug, text } from "@micacms/core";

export const site = defineSite({
  root: "./content",
  collections: {
    news: collection({
      label: "News",
      fields: {
        title: text({ required: true, listed: true }),
        slug: slug({ from: "title" }),
        body: richText(),
      },
    }),
  },
});

3. Add the Astro collections

Create src/content.config.ts.

import { micaCollections } from "@micacms/astro";
import { site } from "./mica";

export const collections = micaCollections(site);

astro.config stays as it is. Start the Astro dev server once. The loader writes content/.mica/schema.json. Commit that file: it tells Mica what your project can edit.

4. Start Mica

npx @micacms/editor

The command prints the address and opens your browser on http://localhost:6422/admin/.

The editor opens directly. On your machine Mica runs without an identity provider, so there is no account and no password to create. It listens on the local computer only, and refuses to run this way on a server.

To pin the editor's version with the project, install it as a dev dependency and add a script:

npm install --save-dev @micacms/editor

{
  "scripts": {
    "mica": "mica"
  }
}

npm run mica then starts the same editor, at the version your lockfile holds, for everyone who works on the project.

5. Render the content

Use normal Astro Content Layer calls.

---
import { getCollection } from "astro:content";
const news = await getCollection("news");
---

{news.map((article) => <h2>{article.data.title}</h2>)}

6. Save, then publish

A save writes files into your working tree, and the Astro dev server reloads them at once. Run git diff after a save: the whole change is there as JSON, Markdoc and media files, uncommitted.

Nothing reaches the repository's history until you press Publish. The Publish page lists every pending change and can show, field by field, what each one does. Publishing turns the reviewed changes into one commit and pushes it with your own Git configuration.