@natilon/astro-cms 0.5.0 → 0.9.0

package/README.md

@@ -1,70 +1,195 @@
 # @natilon/astro-cms
 
-Astro integration that mounts [`@natilon/cms-server`](../cms-server) +
-[`@natilon/admin-ui`](../admin-ui) into `astro dev`, so the site and
-its CMS run from a single command on a single origin.
-
-In production (`astro build`), this integration does nothing — the CMS
-is a separate Node process you deploy alongside (or behind) the static
-site. Use `@natilon/cms-server`'s `startCmsServer` for that.
+Astro integration for [Natilon CMS](../../README.md). Mounts the CMS admin panel into `astro dev`, auto-generates content collection config, and exports the JSON loader + schema builder your site needs.
 
 ## Install
 
 ```sh
-npm i @natilon/astro-cms @natilon/cms-server @natilon/admin-ui
+npm i @natilon/astro-cms @natilon/cms-server
 ```
 
-## Usage
+## Quick start
+
+### 1. Create `cms.config.mjs`
 
 ```js
-// astro.config.mjs
-import { defineConfig } from "astro/config";
-import natilonCms from "@natilon/astro-cms";
-import cmsConfig, { publicConfig } from "./cms.config.mjs";
-import path from "path";
-import { fileURLToPath } from "url";
+export default {
+  mountPath: "/admin",
+  locales: ["en"],
+  defaultLocale: "en",
+
+  collections: {
+    blog: {
+      label: "Blog Posts",
+      listFields: ["title", "pubDate"],
+      metaFields: [
+        { key: "title",   type: "text",     label: "Title",     required: true },
+        { key: "slug",    type: "text",     label: "Slug",      required: true },
+        { key: "pubDate", type: "datetime", label: "Published" },
+        { key: "blocks",  type: "blocks",   label: "Content" },
+      ],
+    },
+  },
+
+  content: {
+    pagesDir: "src/pages-data",
+    publishBranch: "main",
+    commitMessage: (ts) => `Content updated ${ts}`,
+  },
+
+  media: { provider: "local" },
+
+  auth: {
+    provider: "basic",
+    userEnv: "ADMIN_USER",
+    passEnv: "ADMIN_PASS",
+  },
+};
+```
+
+### 2. Mount in `astro.config.mjs`
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+```js
+import { defineConfig } from "astro/config";
+import natilon from "@natilon/astro-cms";
+import config from "./cms.config.mjs";
 
 export default defineConfig({
-  integrations: [
-    natilonCms({
-      config: cmsConfig,
-      publicConfig,
-      rootDir: __dirname,
-      adminUiSourceDir: path.join(__dirname, "node_modules/@natilon/admin-ui"),
-      realm: "My Site Admin",
-    }),
-  ],
+  integrations: [natilon({ config })],
 });
 ```
 
-Now `npm run dev` boots Astro's Vite server with the admin mounted at
-`/admin`. No second process needed for local development.
+### 3. Run `astro dev` — `src/content.config.ts` is generated automatically
 
-## Content helpers
+```
+✔ Generated src/content.config.ts — covers blog. Edit freely.
+```
+
+The generated file covers every collection in `cms.config.mjs`. You can commit it, and adding a new collection to `cms.config.mjs` requires no changes to it. Delete it to regenerate.
+
+### 4. Add env vars (`.env`)
+
+```
+ADMIN_USER=admin
+ADMIN_PASS=secret
+```
+
+### 5. Render blocks in your pages
+
+```astro
+---
+import BlockRenderer from "@natilon/astro-blocks";
+const { entry } = Astro.props;
+---
+<BlockRenderer blocks={entry.data.blocks} />
+```
+
+See [`@natilon/astro-blocks`](../astro-blocks/README.md) for the full block reference.
+
+---
+
+## `cms.config.mjs` reference
+
+### Collection options
 
 ```js
-import { listEntries, getEntry } from "@natilon/astro-cms/content";
-
-// In a .astro file:
-const posts = await listEntries({
-  rootDir: process.cwd(),
-  pagesDir: "src/pages-data",
-  collection: "blog",
-  locales: ["en", "tr"],
-});
+collections: {
+  blog: {
+    label: "Blog Posts",          // displayed in sidebar
+    listFields: ["title", "slug"], // columns shown in entry list
+    metaFields: [ ... ],          // editable fields
+    defaultValues: { draft: true },
+  },
+}
 ```
 
-These read the same JSON files the CMS writes. Use them from
-`getStaticPaths()` to drive Astro routes.
+### `metaFields` field types
+
+| `type`           | Editor control                        | Zod type (auto)              |
+|------------------|---------------------------------------|------------------------------|
+| `text`           | Single-line input                     | `z.string().optional()`      |
+| `textarea`       | Multi-line input                      | `z.string().optional()`      |
+| `richtext`       | Rich-text editor (HTML output)        | `z.string().optional()`      |
+| `number`         | Numeric input                         | `z.number().optional()`      |
+| `boolean`        | Toggle                                | `z.boolean().optional()`     |
+| `date`           | Date picker                           | `z.coerce.date().optional()` |
+| `datetime`       | Date + time picker                    | `z.coerce.date().optional()` |
+| `select`         | Dropdown (`options: [...]` required)  | `z.enum([...]).optional()`   |
+| `image`          | Media picker (CDN or local)           | `z.string().optional()`      |
+| `meta-image`     | OG/social image picker                | `z.string().nullable().optional()` |
+| `json`           | Raw JSON textarea                     | `z.unknown().optional()`     |
+| `collection-ref` | Entry picker from another collection  | `z.string().optional()`      |
+| `blocks`         | Block content editor (see astro-blocks)| auto-included always        |
+| `code`           | Code editor                           | `z.string().optional()`      |
+
+**Options:**
+
+```js
+{ key: "status", type: "select", label: "Status", options: ["draft", "published"], required: true }
+{ key: "cover",  type: "image",  label: "Cover image" }
+{ key: "source", type: "collection-ref", label: "Author", collection: "authors" }
+```
+
+`required: true` shows a red `*` in the editor and blocks saving if the field is empty.
+
+### Custom block types
+
+```js
+// cms.config.mjs — optional, extends the built-in block palette
+blocks: {
+  hero: {
+    label: "Hero",
+    icon: "fa-star",
+    properties: {
+      heading: { type: "text",     label: "Heading", required: true },
+      image:   { type: "image",    label: "Background image" },
+      cta:     { type: "text",     label: "Button text" },
+      ctaHref: { type: "text",     label: "Button URL" },
+    },
+    defaults: { heading: "Welcome" },
+  },
+},
+```
+
+---
+
+## Content helpers
+
+`jsonContentLoader` and `buildCollectionSchema` are re-exported from the main entry:
+
+```ts
+import { jsonContentLoader, buildCollectionSchema } from "@natilon/astro-cms";
+```
+
+### `jsonContentLoader(collection, opts?)`
+
+Astro Content Layer loader. Reads `src/pages-data/{collection}/*.json` (or `opts.pagesDir`).
+
+```ts
+loader: jsonContentLoader("blog")
+loader: jsonContentLoader("blog", { pagesDir: "content/pages" })
+```
+
+### `buildCollectionSchema(collectionConfig, { z })`
+
+Generates a Zod schema from a collection's `metaFields`. Always includes `slug`, `lang`, `draft`, `publishAt`, `blocks`, and standard taxonomy arrays.
+
+```ts
+// Extend to tighten types:
+schema: buildCollectionSchema(config.collections.blog, { z }).extend({
+  pubDate: z.coerce.date(),    // make date required (not optional)
+}),
+```
+
+---
+
+## Integration options
 
-## Options
+| Option             | Type       | Default                         |
+|--------------------|------------|---------------------------------|
+| `config`           | `Object`   | **required** — your cms.config  |
+| `publicConfig`     | `Function` | auto-derived (strips secrets)   |
+| `rootDir`          | `string`   | Astro's `config.root`           |
+| `adminUiSourceDir` | `string`   | path to admin-ui for HMR dev    |
+| `realm`            | `string`   | HTTP Basic auth realm           |
 
-| Option              | Type                       | Default                                |
-| ------------------- | -------------------------- | -------------------------------------- |
-| `config`            | `Object` (required)        | your `cms.config` object               |
-| `publicConfig`      | `() => Object`             | sanitizer for `/api/config`            |
-| `rootDir`           | `string`                   | Astro's `config.root`                  |
-| `adminUiSourceDir`  | `string`                   | path to `@natilon/admin-ui` package    |
-| `realm`             | `string`                   | HTTP basic-auth realm                  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natilon/astro-cms",
-  "version": "0.5.0",
+  "version": "0.9.0",
   "description": "Astro integration that mounts the Natilon CMS admin under /admin during `astro dev` and exposes content helpers.",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,7 @@
   ],
   "peerDependencies": {
     "@natilon/cms-server": "*",
-    "astro": "^4.0.0 || ^5.0.0",
+    "astro": "^4.0.0 || ^5.0.0 || ^6.0.0",
     "zod": "^3.0.0"
   },
   "peerDependenciesMeta": {

package/src/index.mjs

@@ -1,6 +1,35 @@
 import { fileURLToPath } from "url";
+import fs from "fs";
+import path from "path";
 import { createCmsServer, mountAdminUi } from "@natilon/cms-server";
 
+export { jsonContentLoader } from "./loader.mjs";
+export { buildCollectionSchema } from "./schema.mjs";
+
+/**
+ * Generate the content of src/content.config.ts for a new project.
+ * The generated file is safe to commit and customise.
+ */
+function generateContentConfig() {
+  return `\
+// Auto-generated by @natilon/astro-cms — safe to commit and customize.
+// Delete this file and restart dev to regenerate from cms.config.mjs.
+import { defineCollection, z } from "astro:content";
+import { jsonContentLoader, buildCollectionSchema } from "@natilon/astro-cms";
+import config from "../cms.config.mjs";
+
+export const collections = Object.fromEntries(
+  Object.entries(config.collections).map(([name, col]) => [
+    name,
+    defineCollection({
+      loader: jsonContentLoader(name),
+      schema: buildCollectionSchema(col, { z }),
+    }),
+  ])
+);
+`;
+}
+
 /**
  * Astro integration for the Natilon CMS.
  *
@@ -8,6 +37,9 @@ import { createCmsServer, mountAdminUi } from "@natilon/cms-server";
  * Astro's Vite server, so the site and `/admin` are served from one origin.
  * In `astro build`, does nothing — the CMS is a separate process in prod.
  *
+ * Auto-generates `src/content.config.ts` from `cms.config.mjs` if the file
+ * does not already exist, so new projects skip the manual wiring step.
+ *
  * @param {Object} opts
  * @param {Object} opts.config              cms.config object (imported by the consumer)
  * @param {() => Object} [opts.publicConfig] returns sanitized config for the browser
@@ -20,6 +52,44 @@ export default function natilonCms(opts = {}) {
   return {
     name: "@natilon/astro-cms",
     hooks: {
+      "astro:config:setup": ({ config: astroConfig, logger }) => {
+        // Resolve project root — Astro 5 gives a URL object, earlier versions a string.
+        let rootDir = opts.rootDir;
+        if (!rootDir) {
+          const r = astroConfig.root;
+          if (!r) {
+            rootDir = process.cwd();
+          } else if (typeof r === "object" && typeof r.pathname === "string") {
+            // URL object (Astro 5+)
+            rootDir = fileURLToPath(r);
+          } else if (typeof r === "string" && r.startsWith("file://")) {
+            rootDir = fileURLToPath(new URL(r));
+          } else {
+            rootDir = String(r);
+          }
+        }
+
+        // Auto-generate content.config.ts only when all of these hold:
+        //  1. No existing content config file is found
+        //  2. The cms.config has at least one collection defined
+        const candidates = [
+          path.join(rootDir, "src", "content.config.ts"),
+          path.join(rootDir, "src", "content.config.js"),
+          path.join(rootDir, "src", "content.config.mjs"),
+          path.join(rootDir, "src", "content", "config.ts"),
+          path.join(rootDir, "src", "content", "config.js"),
+        ];
+
+        if (candidates.some((f) => fs.existsSync(f))) return;
+        if (!opts.config?.collections || Object.keys(opts.config.collections).length === 0) return;
+
+        const target = path.join(rootDir, "src", "content.config.ts");
+        fs.writeFileSync(target, generateContentConfig(), "utf8");
+        logger.info(
+          `Generated src/content.config.ts — covers ${Object.keys(opts.config.collections).join(", ")}. Edit freely.`
+        );
+      },
+
       "astro:server:setup": async ({ server, logger }) => {
         // server is Astro's underlying Vite dev server.
         const rootDir = (() => {
@@ -68,3 +138,4 @@ export default function natilonCms(opts = {}) {
 }
 
 export { createCmsServer, mountAdminUi };
+