Quick start

Coming with v1. The npm commands on this page describe the public release. The packages polaris-cms and create-polaris-cms are not published yet, so these commands don't work today. See Today: the Polaris CMS kit for what is available now.

A new site#

One command will create an Astro or Next.js starter with Polaris built in: the blog pages, /studio, the API, the migrations and a Dockerfile.

npm create polaris-cms@latest my-site

An existing Astro site#

Install the package and add the integration. It adds /studio, the API routes under /api/cms/ and the migrations.

npm install polaris-cms

// astro.config.mjs (planned shape, coming with v1)
import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import polaris from "polaris-cms/astro";

export default defineConfig({
  adapter: node({ mode: "standalone" }),
  integrations: [polaris()],
});

Your static pages stay static. Only the CMS routes render on the server.

An existing Next.js site#

Install the package and add one route file that re-exports the handlers.

npm install polaris-cms

// One route file in your app/ directory (planned shape, coming with v1)
export { GET, POST } from "polaris-cms/next";

The file location and the import paths above are a sketch of the plan, not final names. The v1 docs will fix them.

After installing (all three ways)#

1. Point DATABASE_URL at a PostgreSQL 16+ database. Migrations run on start.
2. Set ADMIN_USERNAME and ADMIN_PASSWORD (and a session secret). See Deployment.
3. Open /studio on your site and sign in.
4. Create an API key under API Keys if an agent or a script will publish. See Using with AI agents.
5. Write the first post, or send it through the API.

Updates will come through npm update. Polaris runs anywhere Node runs, and a Docker recipe is included.

Today: the Polaris CMS kit#

Until v1 is out, the Polaris CMS kit is available on request: write to hello@scentro.pl. It is the /studio CMS on its own, with its API, database schema and migrations, in an Astro version and a Next.js version, plus step-by-step instructions for adding it to a site you already have.

Adding the Astro version to an existing site, in short:

1. Copy astro/src/* into your src/, and astro/migrations and astro/scripts into the project root. If you already have a middleware.ts, merge the /studio gate into it.

2. Install the packages the kit is tested with:

   npm i @astrojs/node@11.1.9 @astrojs/react@7.1.2 drizzle-orm@0.45.4 postgres@3.4.9 react@19.3.1 react-dom@19.3.1 react-markdown@10.1.0 remark-gfm@4.0.1 sharp@0.35.5
   npm i -D tailwindcss@4.3.4 @tailwindcss/vite@4.3.4

3. In tsconfig.json, add "paths": { "@cms/*": ["./src/cms/*"] } and "jsx": "react-jsx".

4. In astro.config: adapter: node({ mode: "standalone" }), integrations: [react({ include: ["src/cms/**/*.tsx"] })] and vite: { plugins: [tailwindcss()] }. Static pages stay static; the CMS routes opt out with prerender = false.

5. Edit src/config/site.ts (name, URL, locale) and src/config/pages.ts (the pages Link Genius and IndexNow offer).

6. Add the blog pages that show the posts, using the public read functions in @cms/journal/public.server.

The Next.js version follows the same idea: copy src/app/studio, src/app/api/cms, src/lib/studio, src/lib/blog and src/db, use output: "standalone", and gate /studio in its layout (no middleware needed). Then, for both:

export DATABASE_URL=postgres://user:pass@host:5432/db
npm run db:migrate

Sign in at /studio, create an API key and hand it to your agents.