@pramen/cms-astro 0.0.50 → 0.0.52

package/README.md

@@ -3,6 +3,63 @@
 Consume a [`@pramen/cms`](../cms) backend from an **Astro** site. Self-contained (no
 `@pramen/server` dependency — it speaks the CMS's public HTTP content API).
 
+## The front door: `pramenCms()`
+
+One integration, and the collections come from the store:
+
+```ts
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import pramenCms from "@pramen/cms-astro";
+
+export default defineConfig({
+  integrations: [pramenCms({ backend: { url: "https://cms.example.workers.dev" } })],
+});
+```
+
+```ts
+// src/content.config.ts — once, and never again
+export { collections } from "pramen:cms";
+```
+
+That is the whole wiring. `collections: "auto"` (the default) asks the CMS which content
+types exist and generates one collection per type, named after its slug — so adding a
+content type in the editor takes effect on the next build with no code change. Pass a map
+when you want your own names or a subset: `collections: { clanky: "article" }`.
+
+The `pramen:cms` virtual module also exports the **configured client** and a bound
+**`resolve()`**, so a component that needs a media URL imports it instead of
+re-instantiating the client with a duplicated base URL:
+
+```astro
+---
+import { client, resolve } from "pramen:cms";
+const page = await client.getPage("o-nas");
+---
+<img src={resolve(page.page.fields.hero.url)} alt="" />
+```
+
+Types for that module are injected automatically (`pramen-cms.d.ts`), so there is no
+hand-written `d.ts` to keep in step.
+
+**Why the one-line re-export?** Astro has no API for an integration to define content
+collections — `astro:config:setup` offers routes, scripts, middleware, renderers and Vite
+config, and nothing for the content layer. Collections must be exported from
+`src/content.config.ts`. So the integration generates them and you re-export once, instead
+of hand-writing a `defineCollection` per type that has to track rows in the store.
+
+**`"auto"` fails the build if it cannot reach the CMS**, rather than generating nothing.
+Zero collections would otherwise build green and deploy an empty site. Discovery reads
+`listPublicContentTypes`, which is un-gated — no build-time token needed, and nothing new is
+exposed (a content type's slug already reaches the public through `listPublishedPages`). If
+your deployment does need auth for reads, pass `backend: { token }`.
+
+`createCmsClient` / `cmsLoader` stay exported and are documented below — the integration is
+the front door, not a replacement. A site that wants to define its own collections by hand
+still can.
+
+## The kit of parts
+
 - **`createCmsClient({ baseUrl })`** — `getPage(slug, locale?)`, `listPublishedPages()`, and
   `getPreview(token)` to redeem a signed preview link (no session needed — the signature is
   the authorization; the result carries `isPreview: true`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/cms-astro",
-  "version": "0.0.50",
+  "version": "0.0.52",
   "description": "Astro integration for @pramen/cms \u2014 a build-time content-collection loader + a BlockRenderer for rendering CMS blocks in .astro pages.",
   "license": "MIT",
   "repository": {
@@ -14,6 +14,7 @@
   "sideEffects": false,
   "exports": {
     ".": "./src/index.ts",
+    "./integration": "./src/integration.ts",
     "./BlockRenderer.astro": "./src/BlockRenderer.astro",
     "./RichText.astro": "./src/RichText.astro",
     "./RichTextMarks.astro": "./src/RichTextMarks.astro"

package/src/index.ts

@@ -11,6 +11,12 @@
 
 import type { Loader, LoaderContext } from "astro/loaders";
 
+// The integration — the front door (`pramenCms()`), re-exported so
+// `import pramenCms from "@pramen/cms-astro"` works. The kit of parts below stays exported:
+// a site that defines its own collections by hand still can.
+export { pramenCms, default } from "./integration.js";
+export type { CmsBackend, CollectionMap, PramenCmsOptions } from "./integration.js";
+
 /** Any JSON value — the wire form of everything the CMS stores. */
 export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
 

package/src/integration.ts

@@ -0,0 +1,193 @@
+// The Astro integration — one front door for a @pramen/cms backend (issue #35).
+//
+// Before this, a site hand-wired the kit of parts: instantiate `createCmsClient` in
+// `content.config.ts`, write one `defineCollection({ loader: cmsLoader({ client, type }) })`
+// per content type, then re-instantiate or re-import the client anywhere else that needs
+// `resolve()` for a media URL. Two things drifted: the base URL was repeated at every call
+// site, and the hand-written collection list had to be kept in step with content types that
+// are runtime ROWS — so adding a type in the editor silently did nothing until someone
+// remembered to edit the config.
+//
+// `pramenCms()` owns both. It builds the client once from a typed `backend` descriptor and
+// exposes it (plus the collections) through the `pramen:cms` virtual module.
+//
+// ON REGISTERING COLLECTIONS. Astro has no API for an integration to define content
+// collections — `astro:config:setup` offers routes, scripts, middleware, renderers and Vite
+// config, and nothing for the content layer (checked against Astro 7). Collections must be
+// exported from `src/content.config.ts`. So the integration generates them and the site
+// re-exports in one line:
+//
+//   // src/content.config.ts
+//   export { collections } from "pramen:cms";
+//
+// That is the honest version of "the integration registers them": one line that never
+// changes, instead of one `defineCollection` per type that has to track the store.
+
+import type { AstroIntegration } from "astro";
+import { createCmsClient, type CmsClient } from "./index.js";
+
+/** Where the CMS lives. A named descriptor rather than a bare `baseUrl` string, so a future
+ * local/in-process backend can be added without changing the call shape. */
+export interface CmsBackend {
+  /** The Worker's origin, e.g. `https://cms.example.workers.dev`. */
+  url: string;
+  /** Tenant to read. Default `"main"`. */
+  tenant?: string;
+  /** Bearer token, for reading a private deployment at build time. The public content API
+   * needs none — pass one only if your ACL does not grant anonymous reads. */
+  token?: string;
+}
+
+/** One generated collection: the Astro collection name, and the CMS content type it loads. */
+export type CollectionMap = Record<string, string>;
+
+export interface PramenCmsOptions {
+  backend: CmsBackend;
+  /**
+   * Which collections to generate.
+   *
+   * - `"auto"` (default) — one collection per content type in the store, named after the
+   *   type's slug. Discovered at config time, so adding a type in the editor takes effect
+   *   on the next build with no code change.
+   * - an explicit map — `{ articles: "article", pages: "page" }` — when you want your own
+   *   names, or a subset.
+   *
+   * `"auto"` costs one request during `astro:config:setup`. If it fails (the CMS is down,
+   * or unreachable from CI) the build FAILS rather than silently producing zero
+   * collections, which would otherwise surface as `getCollection("articles")` returning
+   * nothing and a site that builds green and empty.
+   */
+  collections?: "auto" | CollectionMap;
+  /** Restrict every generated collection to one locale. Omit to load all of them. */
+  locale?: string;
+}
+
+/** The virtual module the site imports from. */
+const VIRTUAL_ID = "pramen:cms";
+const RESOLVED_ID = "\0pramen:cms";
+
+/** Ask the CMS which content types exist. Public and un-gated (`listPublicContentTypes`),
+ * because this runs at BUILD time where there is no editor session — and a content type's
+ * slug is already public: `listPublishedPages` returns it for every published page. */
+async function discoverTypes(backend: CmsBackend): Promise<string[]> {
+  const base = backend.url.replace(/\/+$/, "");
+  const headers: Record<string, string> = { "content-type": "application/json", "x-pramen-tenant": backend.tenant ?? "main" };
+  if (backend.token) headers.authorization = `Bearer ${backend.token}`;
+  const res = await fetch(`${base}/rpc/listPublicContentTypes`, { method: "POST", headers, body: "{}" });
+  const body = (await res.json().catch(() => ({}))) as { ok?: boolean; result?: { slug: string }[]; error?: string };
+  if (body.ok !== true || !Array.isArray(body.result)) {
+    throw new Error(
+      `@pramen/cms-astro: collections: "auto" could not read content types from ${base} (HTTP ${res.status}${body.error ? `: ${body.error}` : ""}). ` +
+        `Pass an explicit map instead — collections: { articles: "article" } — or make the CMS reachable from this build.`,
+    );
+  }
+  return body.result.map((t) => t.slug).filter((s) => typeof s === "string" && s !== "");
+}
+
+/** A valid JS identifier-ish collection name. A content-type slug is author-controlled, and
+ * it lands in generated source as an object key — quote it, and refuse the ones that cannot
+ * be a collection name at all rather than emitting code that fails to parse. */
+function collectionKey(slug: string): string {
+  if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(slug)) {
+    throw new Error(`@pramen/cms-astro: content-type slug ${JSON.stringify(slug)} cannot be a collection name — map it explicitly, e.g. collections: { myName: ${JSON.stringify(slug)} }`);
+  }
+  return slug;
+}
+
+/** Generate the virtual module's source. Everything the site needs from one import:
+ * the configured client, `resolve()` for media URLs, and the collections. */
+function moduleSource(backend: CmsBackend, map: CollectionMap, locale?: string): string {
+  const clientOpts = JSON.stringify({ baseUrl: backend.url, tenant: backend.tenant, token: backend.token });
+  const entries = Object.entries(map)
+    .map(([name, type]) => `  ${collectionKey(name)}: defineCollection({ loader: cmsLoader({ client, type: ${JSON.stringify(type)}${locale ? `, locale: ${JSON.stringify(locale)}` : ""} }) }),`)
+    .join("\n");
+  return `// GENERATED by @pramen/cms-astro (pramenCms integration) — do not edit.
+import { defineCollection } from "astro:content";
+import { createCmsClient, cmsLoader } from "@pramen/cms-astro";
+
+export const client = createCmsClient(${clientOpts});
+
+/** Absolute URL for a media path the CMS returned. Same base as the client, so a component
+ * never has to be handed the client (or a duplicated base URL) just to show an image. */
+export const resolve = (path) => client.resolve(path);
+
+export const collections = {
+${entries}
+};
+`;
+}
+
+/** The `pramen:cms` module's types, injected so the site gets them with no manual d.ts. */
+const TYPES = `declare module "pramen:cms" {
+  import type { CmsClient } from "@pramen/cms-astro";
+  /** The configured CMS client — same instance the collections load through. */
+  export const client: CmsClient;
+  /** Absolute URL for a media path the CMS returned. */
+  export function resolve(path: string): string;
+  /** Generated content collections. Re-export from src/content.config.ts:
+   *  \`export { collections } from "pramen:cms";\` */
+  export const collections: Record<string, unknown>;
+}
+`;
+
+/**
+ * The Astro integration for a @pramen/cms backend.
+ *
+ *   import pramenCms from "@pramen/cms-astro";
+ *
+ *   export default defineConfig({
+ *     integrations: [pramenCms({ backend: { url: "https://cms.example.workers.dev" } })],
+ *   });
+ *
+ * Then, once, in `src/content.config.ts`:
+ *
+ *   export { collections } from "pramen:cms";
+ *
+ * `createCmsClient` / `cmsLoader` stay exported — this is the front door, not a
+ * replacement. A site that wants to define its own collections by hand still can.
+ */
+export function pramenCms(opts: PramenCmsOptions): AstroIntegration {
+  if (!opts?.backend?.url) throw new Error("@pramen/cms-astro: pramenCms() needs a backend url — pramenCms({ backend: { url: \"https://cms.example.workers.dev\" } })");
+  return {
+    name: "@pramen/cms-astro",
+    hooks: {
+      "astro:config:setup": async ({ updateConfig, logger }) => {
+        const wanted = opts.collections ?? "auto";
+        const map: CollectionMap = wanted === "auto" ? Object.fromEntries((await discoverTypes(opts.backend)).map((s) => [collectionKey(s), s])) : wanted;
+        const names = Object.keys(map);
+        if (names.length === 0) {
+          // Not an error: a store with no content types yet is a legitimate early state.
+          // It IS worth saying out loud, because the symptom otherwise is `getCollection`
+          // throwing about a collection the site is sure it configured.
+          logger.warn(`no content types found at ${opts.backend.url} — no collections generated`);
+        } else {
+          logger.info(`${names.length} collection(s) from ${opts.backend.url}: ${names.join(", ")}`);
+        }
+        const code = moduleSource(opts.backend, map, opts.locale);
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: "pramen:cms",
+                // `enforce: "pre"` so this resolves before Astro's own alias handling sees
+                // an unknown bare specifier and reports it as a missing package.
+                enforce: "pre" as const,
+                resolveId(id: string) {
+                  return id === VIRTUAL_ID ? RESOLVED_ID : null;
+                },
+                load(id: string) {
+                  return id === RESOLVED_ID ? code : null;
+                },
+              },
+            ],
+          },
+        });
+      },
+      "astro:config:done": ({ injectTypes }) => {
+        injectTypes({ filename: "pramen-cms.d.ts", content: TYPES });
+      },
+    },
+  };
+}
+
+export default pramenCms;