Skip to content

Getting Started

  1. Install the package
    Terminal window
    npm install astronaut-cms @astrojs/react react react-dom zod
  2. Add the integration to your Astro config
    astro.config.ts
    import { defineConfig } from "astro/config";
    import mdx from "@astrojs/mdx";
    import react from "@astrojs/react";
    import cms from "astronaut-cms";
    export default defineConfig({
    integrations: [mdx(), react(), cms()],
    });
  3. Define your content collections

    Create a src/content.config.ts file using Astro’s standard content collection API:

    src/content.config.ts
    import { defineCollection } from "astro:content";
    import { glob } from "astro/loaders";
    import { z } from "astro/zod";
    const blog = defineCollection({
    loader: glob({ pattern: "**/*.{md,mdx}", base: "src/content/blog" }),
    schema: ({ image }) =>
    z.object({
    title: z.string(),
    description: z.string(),
    date: z.coerce.date(),
    draft: z.boolean().default(false),
    cover: image().optional(),
    }),
    });
    export const collections = { blog };
  4. Start the dev server and open the admin panel
    Terminal window
    npm run dev

    Navigate to http://localhost:4321/admin to access the CMS admin panel.

astro dev edits the working tree and needs no sign-in, so everything above works with no further setup. A deployed CMS is different: it holds the repository session on the server, so it needs two things.

  1. An SSR adapter

    @astrojs/node, @astrojs/cloudflare, @astrojs/vercel, @astrojs/netlify — whichever suits your host. The rest of your site can stay static. The build fails with a message if one is missing, unless admin: false leaves the admin out of the build.

  2. A Git backend

    A GitHub App or GitLab application, whose client id goes in astro.config.ts and whose secret goes in the environment as ASTRONAUT_CMS_GITHUB_CLIENT_SECRET (or ..._GITLAB_...).

    That is the only secret. The session cookie’s key is derived from it, so there is nothing to generate, seed or keep in sync.