create-natilon

Scaffold Natilon CMS into an existing Astro project in seconds.

Usage

Run from inside your Astro project root:

npm create natilon
# or
npx create-natilon

No flags needed — the CLI guides you through everything interactively.

What it does

1. Asks for your site name, locale(s), admin mount path, and which collections to enable
2. Creates cms.config.mjs with full collection definitions
3. Creates src/pages-data/{collection}/ directories (with .gitkeep so they're tracked by git)
4. Creates .env.example with starter CMS credentials
5. Creates src/components/BlockRenderer.astro wired to @natilon/astro-blocks
6. Shows the exact code snippet to add to astro.config.mjs and the install command

Example session

◆  Natilon CMS — project setup

  Adding CMS to: /my-project

  Site name (my-site): My Blog
  Locale(s) (en): en
  Admin mount path (/admin):

  Collections — toggle to include/exclude:
    1. ✓ Blog Posts (blog)
    2. ✓ Pages (pages)
    3.   Glossary (glossary)
    4. ✓ Authors (authors)
    5. ✓ Categories (categories)
    6. ✓ Tags (tags)

  Enter numbers to toggle (e.g. 1 3 5), or press Enter to keep defaults:
  >

  ✓ Created  cms.config.mjs
  ✓ Created  src/pages-data/{blog,pages,authors,categories,tags}/
  ✓ Created  .env.example
  ✓ Created  src/components/BlockRenderer.astro

  Next steps:
  ...

After running

1. Install packages

npm install @natilon/astro-cms @natilon/cms-server @natilon/admin-ui @natilon/astro-blocks

2. Add the integration to astro.config.mjs

import natilonCms from "@natilon/astro-cms";
import cmsConfig, { publicConfig } from "./cms.config.mjs";
import { fileURLToPath } from "url";
import path from "path";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

export default defineConfig({
  integrations: [
    natilonCms({
      config: cmsConfig,
      publicConfig,
      rootDir: __dirname,
      adminUiSourceDir: path.join(__dirname, "node_modules/@natilon/admin-ui"),
      realm: "My Site Admin",
    }),
  ],
});

3. Set credentials

cp .env.example .env
# Edit .env: set CMS_USERNAME and CMS_PASSWORD

4. Start dev

npm run dev

The admin is at /admin. On first start, src/content.config.ts is auto-generated from cms.config.mjs — commit it once it looks right.

Collections

| Value | Label | Includes | |--------------|-------------|----------------------------------------------------| | blog | Blog Posts | title, pubDate, author, categories, tags, blocks | | pages | Pages | title, SEO fields, blocks | | glossary | Glossary | term, SEO fields, blocks | | authors | Authors | name, bio, avatar, url | | categories | Categories | name, description | | tags | Tags | name |

All collections can be freely edited in cms.config.mjs after scaffolding.

Requirements

• Node.js ≥ 20.12
• An existing Astro project (astro.config.* in the current directory)