create-headroom-site 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-headroom-site",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Scaffold a new Headroom CMS frontend site (Astro or Next.js)",
   "type": "module",
   "license": "PolyForm-Noncommercial-1.0.0",

package/templates/astro/CLAUDE.md

@@ -0,0 +1,364 @@
+# Headroom CMS - Astro Site
+
+This is an Astro site powered by [Headroom CMS](https://github.com/headroom-cms), a serverless headless CMS. Content is managed in the Headroom admin UI and fetched at build time via the `@headroom-cms/api` SDK.
+
+## Tech Stack
+
+- **Astro** (static output) with content collections
+- **@headroom-cms/api** SDK for data fetching and block rendering
+- **Tailwind CSS v4** for styling
+
+## Project Structure
+
+```
+src/
+├── content.config.ts        # Astro content collections backed by Headroom loader
+├── lib/
+│   ├── client.ts            # Singleton HeadroomClient instance
+│   ├── links.ts             # Content link resolver (maps refs to URL paths)
+│   └── schemas.ts           # Auto-generated Zod schemas (run generate:schemas)
+├── layouts/
+│   └── BaseLayout.astro     # Shell with Header, Footer, <slot />
+├── components/              # Reusable Astro components
+├── pages/
+│   ├── index.astro          # Homepage
+│   ├── blog/
+│   │   ├── index.astro      # Blog listing
+│   │   └── [slug].astro     # Blog post detail
+│   ├── [...slug].astro      # Dynamic pages from "pages" collection
+│   └── 404.astro
+└── styles/
+    └── global.css           # Tailwind imports
+```
+
+## Environment Variables
+
+Copy `_env.example` to `.env` and fill in your Headroom credentials:
+
+```bash
+HEADROOM_URL=https://your-headroom-url.cloudfront.net
+HEADROOM_SITE=your-site.com
+HEADROOM_API_KEY=headroom_xxxxx
+HEADROOM_IMAGE_SIGNING_SECRET=your-secret  # optional, for image transforms
+```
+
+## Commands
+
+```bash
+npm run dev               # Start Astro dev server
+npm run build             # Build static site
+npm run preview           # Preview built site
+npm run generate:schemas  # Generate Zod schemas from Headroom collections
+```
+
+## Default Collections
+
+New Headroom sites are scaffolded with three collections:
+
+| Collection | Type | Description |
+|------------|------|-------------|
+| `posts` | Standard | Blog posts with `author` (text) and `content` (blocks) fields; use the `featured` tag to mark featured posts |
+| `pages` | Standard | Generic pages with a `content` (blocks) field |
+| `site-settings` | Singleton | Site name, tagline, footer text, and menu items |
+
+## How Data Fetching Works
+
+This site uses **two approaches** to fetch content:
+
+### 1. Astro Content Collections (for listings and metadata)
+
+Content collections are defined in `src/content.config.ts` using `headroomLoader()`. This loads content metadata into Astro's content layer at build time, enabling `getCollection()` and `getEntry()`:
+
+```ts
+// src/content.config.ts
+import { defineCollection } from "astro:content";
+import { headroomLoader } from "@headroom-cms/api/astro";
+
+export const collections = {
+  posts: defineCollection({
+    loader: headroomLoader({ collection: "posts" }),
+  }),
+  pages: defineCollection({
+    loader: headroomLoader({ collection: "pages", bodies: true }),
+  }),
+};
+```
+
+Use `bodies: true` when you need the full block content in the content layer (e.g., for pages). Omit it for listings where you only need metadata.
+
+```astro
+---
+import { getCollection, getEntry } from "astro:content";
+
+// List all posts
+const posts = await getCollection("posts");
+
+// Get a singleton
+const settings = await getEntry("site-settings", "site-settings");
+const siteName = settings?.data.body?.siteName as string;
+---
+```
+
+### 2. Direct SDK Client (for full content with body and refs)
+
+For detail pages that need the full block body and content references (`_refs`), use the SDK client directly:
+
+```astro
+---
+import { getClient } from "../lib/client";
+import type { Block, RefsMap } from "@headroom-cms/api";
+
+const client = getClient();
+const post = await client.getContentBySlug("posts", "my-post");
+
+const blocks = (post.body?.content || []) as Block[];
+const refs = (post._refs || {}) as RefsMap;
+---
+```
+
+### SDK Client Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `listContent(collection, opts?)` | `{ items, cursor, hasMore }` | List published content with pagination/filtering |
+| `getContent(contentId)` | `ContentItem` | Get single item by ID (includes body + refs) |
+| `getContentBySlug(collection, slug)` | `ContentItem \| undefined` | Look up by slug |
+| `getSingleton(collection)` | `ContentItem` | Get singleton content (e.g. site settings) |
+| `listCollections()` | `{ items }` | List all collections |
+| `getCollection(name)` | `Collection` | Get collection schema |
+| `mediaUrl(path)` | `string` | Full URL for a media path |
+| `transformUrl(path, opts?)` | `string` | Signed image transform URL |
+
+### listContent Options
+
+```ts
+const { items, cursor, hasMore } = await client.listContent("posts", {
+  limit: 10,
+  cursor: "...",             // pagination
+  sort: "published_desc",    // published_desc | published_asc | title_asc | title_desc
+  before: 1700000000,        // unix timestamp filter
+  after: 1690000000,
+  relatedTo: "01ABC",        // reverse relationship query
+  relField: "author",        // filter reverse query to specific field
+});
+```
+
+## Rendering Blocks
+
+Content bodies are arrays of [BlockNote](https://www.blocknotejs.org/) blocks. Use the Astro `BlockRenderer` component to render them as semantic HTML with zero client-side JavaScript:
+
+```astro
+---
+import BlockRenderer from "@headroom-cms/api/blocks/BlockRenderer.astro";
+import type { Block, RefsMap } from "@headroom-cms/api";
+
+const blocks = (post.body?.content || []) as Block[];
+const refs = (post._refs || {}) as RefsMap;
+---
+
+<div class="prose">
+  <BlockRenderer
+    blocks={blocks}
+    refs={refs}
+    resolveContentLink={(ref) => `/${ref.collection}/${ref.slug}`}
+    transformImage={(path) => client.transformUrl(path, { width: 1200, format: "webp" })}
+  />
+</div>
+```
+
+### BlockRenderer Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `blocks` | `Block[]` | Block content array from `post.body.content` |
+| `refs` | `RefsMap?` | Content reference map from `post._refs` (resolves `headroom://` links) |
+| `resolveContentLink` | `(ref: PublicContentRef) => string` | Maps content references to URL paths |
+| `transformImage` | `(path: string) => string` | Transforms image paths (e.g., for responsive images) |
+| `baseUrl` | `string?` | Base URL for media (defaults to `HEADROOM_URL` env var) |
+| `class` | `string?` | CSS class for the wrapper `<div>` |
+
+### Block Types
+
+Built-in block types: `paragraph`, `heading`, `image`, `codeBlock`, `bulletListItem`, `numberedListItem`, `checkListItem`, `table`
+
+Astro block components render semantic HTML (`<p>`, `<h1>`-`<h6>`, `<ul>`, `<ol>`, `<figure>`, `<table>`) that work naturally with Tailwind's `prose` class.
+
+### Custom Block Rendering in Astro
+
+To add custom block types or override built-in rendering, create your own renderer that wraps the individual block components:
+
+```astro
+---
+// src/components/CustomBlockRenderer.astro
+import Paragraph from "@headroom-cms/api/blocks/Paragraph.astro";
+import Heading from "@headroom-cms/api/blocks/Heading.astro";
+import Image from "@headroom-cms/api/blocks/Image.astro";
+import CodeBlock from "@headroom-cms/api/blocks/CodeBlock.astro";
+import BulletList from "@headroom-cms/api/blocks/BulletList.astro";
+import NumberedList from "@headroom-cms/api/blocks/NumberedList.astro";
+import CheckList from "@headroom-cms/api/blocks/CheckList.astro";
+import Table from "@headroom-cms/api/blocks/Table.astro";
+import Fallback from "@headroom-cms/api/blocks/Fallback.astro";
+import MyCallout from "./MyCallout.astro";
+
+const { blocks, refs, resolveContentLink, transformImage } = Astro.props;
+---
+
+{blocks.map((block) => {
+  if (block.type === "callout") return <MyCallout block={block} />;
+  if (block.type === "paragraph") return <Paragraph block={block} refs={refs} resolveContentLink={resolveContentLink} />;
+  if (block.type === "heading") return <Heading block={block} refs={refs} resolveContentLink={resolveContentLink} />;
+  if (block.type === "image") return <Image block={block} transformImage={transformImage} />;
+  if (block.type === "codeBlock") return <CodeBlock block={block} />;
+  if (block.type === "bulletListItem") return <BulletList block={block} refs={refs} resolveContentLink={resolveContentLink} />;
+  if (block.type === "numberedListItem") return <NumberedList block={block} refs={refs} resolveContentLink={resolveContentLink} />;
+  if (block.type === "checkListItem") return <CheckList block={block} refs={refs} resolveContentLink={resolveContentLink} />;
+  if (block.type === "table") return <Table block={block} refs={refs} resolveContentLink={resolveContentLink} />;
+  return <Fallback block={block} />;
+})}
+```
+
+## Content Links
+
+Rich text can contain links to other Headroom content using `headroom://content/{collection}/{contentId}` URLs. The `_refs` map on each content item resolves these to metadata (slug, title, collection, published status).
+
+The `BlockRenderer` resolves these automatically using the `resolveContentLink` prop. Define your URL mapping in `src/lib/links.ts`:
+
+```ts
+import type { PublicContentRef } from "@headroom-cms/api";
+
+export function resolveContentLink(ref: PublicContentRef): string {
+  switch (ref.collection) {
+    case "posts":
+      return `/blog/${ref.slug}`;
+    default:
+      return `/${ref.slug}`;
+  }
+}
+```
+
+## Relationships
+
+Collections can define relationships to other collections. Access them on content items:
+
+```ts
+// Forward: get a project's related artists
+const project = await client.getContent("01ABC");
+const artists = project.relationships?.artists; // ContentRef[]
+
+// Reverse: find all projects referencing an artist
+const { items } = await client.listContent("projects", {
+  relatedTo: "01ARTIST",
+  relField: "artists",
+});
+```
+
+## Images and Media
+
+Media paths in content are relative (e.g., `/media/site/id/original.jpg`). Use the client to build full URLs:
+
+```ts
+const client = getClient();
+
+// Full URL for original image
+client.mediaUrl(post.data.coverUrl);
+
+// Signed transform URL (resized + webp)
+client.transformUrl(post.data.coverUrl, { width: 800, format: "webp" });
+```
+
+### Transform Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `width` | `number` | Target width in pixels |
+| `height` | `number` | Target height in pixels |
+| `fit` | `"cover" \| "contain" \| "fill" \| "inside" \| "outside"` | Resize fit mode |
+| `format` | `"webp" \| "avif" \| "jpeg" \| "png"` | Output format |
+| `quality` | `number` | 1-100 quality |
+
+Transforms require `HEADROOM_IMAGE_SIGNING_SECRET` in `.env`. Without it, `transformUrl()` falls back to `mediaUrl()`.
+
+## Dev Refresh
+
+The `headroomDevRefresh()` integration in `astro.config.mjs` polls Headroom for content version changes and triggers automatic reloads during `astro dev`.
+
+## Schema Generation
+
+Run `npm run generate:schemas` to generate Zod schemas from your Headroom collections into `src/lib/schemas.ts`. This provides type-safe validation in content collections. Regenerate after changing collection schemas in the admin UI.
+
+## Adding a New Collection
+
+1. Create the collection in the Headroom admin UI
+2. Add it to `src/content.config.ts`:
+   ```ts
+   projects: defineCollection({
+     loader: headroomLoader({ collection: "projects" }),
+   }),
+   ```
+3. Create pages (listing + detail) under `src/pages/`
+4. Update `src/lib/links.ts` to map the new collection to URL paths
+5. Run `npm run generate:schemas` to update type definitions
+
+## Adding a New Page for Existing Content
+
+Example: adding a page that lists posts filtered by a relationship.
+
+```astro
+---
+// src/pages/author/[id].astro
+import { getClient } from "../../lib/client";
+import BaseLayout from "../../layouts/BaseLayout.astro";
+import PostCard from "../../components/PostCard.astro";
+
+const { id } = Astro.params;
+const client = getClient();
+const { items: posts } = await client.listContent("posts", {
+  relatedTo: id,
+  relField: "author",
+});
+---
+
+<BaseLayout title="Author Posts">
+  <div class="max-w-5xl mx-auto py-12 px-6">
+    <div class="grid md:grid-cols-3 gap-8">
+      {posts.map((post) => (
+        <PostCard title={post.title} snippet={post.snippet} slug={post.slug} />
+      ))}
+    </div>
+  </div>
+</BaseLayout>
+```
+
+## Error Handling
+
+```ts
+import { HeadroomClient, HeadroomError } from "@headroom-cms/api";
+
+try {
+  const post = await client.getContent("nonexistent");
+} catch (e) {
+  if (e instanceof HeadroomError) {
+    console.log(e.status); // 404
+    console.log(e.code);   // "CONTENT_NOT_FOUND"
+  }
+}
+```
+
+## Key Types
+
+```ts
+import type {
+  ContentItem,        // Full content item with body, refs, relationships
+  ContentMetadata,    // Content without body (listings)
+  Block,              // A BlockNote block
+  RefsMap,            // Map of content ID -> PublicContentRef
+  PublicContentRef,   // { contentId, collection, slug, title, published }
+  ContentRef,         // Relationship reference
+  Collection,         // Collection schema
+  FieldDef,           // Field definition in a collection
+  RelationshipDef,    // Relationship definition
+  HeadroomConfig,     // Client configuration
+  TransformOptions,   // Image transform options
+} from "@headroom-cms/api";
+```

package/templates/astro/package.json

@@ -5,15 +5,17 @@
   "scripts": {
     "dev": "astro dev",
     "build": "astro build",
-    "preview": "astro preview"
+    "preview": "astro preview",
+    "generate:schemas": "bash scripts/generate-schemas.sh"
   },
   "dependencies": {
     "astro": "^5.0.0",
-    "@headroom-cms/api": "^0.1.3"
+    "@headroom-cms/api": "^0.1.4"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.0.0",
     "tailwindcss": "^4.0.0",
+    "tsx": "^4.0.0",
     "typescript": "^5.9.3"
   }
 }

package/templates/astro/scripts/generate-schemas.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Generates Zod schemas from Headroom collection definitions.
+# Requires: .env with HEADROOM_* vars, API accessible.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SITE_DIR="$(dirname "$SCRIPT_DIR")"
+
+if [ ! -f "$SITE_DIR/.env" ]; then
+  echo "Error: .env not found. Create a .env file with HEADROOM_URL, HEADROOM_SITE, and HEADROOM_API_KEY." >&2
+  exit 1
+fi
+
+cd "$SITE_DIR"
+npx tsx scripts/generate-schemas.ts

package/templates/astro/scripts/generate-schemas.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env tsx
+/**
+ * Generates Zod schemas from Headroom collection definitions.
+ * Reads connection details from .env and writes src/lib/schemas.ts.
+ *
+ * Usage: npx tsx scripts/generate-schemas.ts
+ */
+
+import { writeFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { HeadroomClient } from "@headroom-cms/api";
+import { generateZodSchemas } from "@headroom-cms/api/codegen";
+import { configFromEnv } from "@headroom-cms/api/astro";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const siteDir = resolve(__dirname, "..");
+
+const config = configFromEnv();
+if (!config.site || !config.apiKey) {
+  console.error("Error: HEADROOM_SITE and HEADROOM_API_KEY must be set in .env");
+  process.exit(1);
+}
+
+const client = new HeadroomClient(config);
+const output = await generateZodSchemas(client);
+
+const outPath = resolve(siteDir, "src/lib/schemas.ts");
+writeFileSync(outPath, output, "utf-8");
+console.log(`Schemas generated at src/lib/schemas.ts`);

package/templates/astro/src/components/Footer.astro

@@ -1,5 +1,13 @@
+---
+import { getEntry } from "astro:content";
+
+const settingsEntry = await getEntry("site-settings", "site-settings");
+const footerText = (settingsEntry?.data.body?.footerText as string) || "";
+---
+
 <footer class="border-t border-gray-100 py-8 mt-16">
   <div class="max-w-5xl mx-auto px-6 text-center text-sm text-gray-500">
+    {footerText && <p class="mb-2">{footerText}</p>}
     <p>
       Powered by <a href="https://headroom.dev" class="hover:underline">Headroom CMS</a>
       &middot; Built with <a href="https://astro.build" class="hover:underline">Astro</a>

package/templates/astro/src/components/Header.astro

@@ -3,6 +3,7 @@ import { getEntry } from "astro:content";
 
 const settingsEntry = await getEntry("site-settings", "site-settings");
 const siteName = (settingsEntry?.data.body?.siteName as string) || "My Site";
+const menuItems = (settingsEntry?.data.body?.menuItems as Array<{ label: string; href: string }>) || [];
 ---
 
 <header class="border-b border-gray-100 bg-white sticky top-0 z-50">
@@ -10,9 +11,12 @@ const siteName = (settingsEntry?.data.body?.siteName as string) || "My Site";
     <a href="/" class="text-xl font-bold tracking-tight hover:opacity-80 transition-opacity">
       {siteName}
     </a>
-    <ul class="flex items-center gap-6">
-      <li><a href="/" class="text-sm font-medium text-gray-600 hover:text-gray-900">Home</a></li>
-      <li><a href="/blog" class="text-sm font-medium text-gray-600 hover:text-gray-900">Blog</a></li>
-    </ul>
+    {menuItems.length > 0 && (
+      <ul class="flex items-center gap-6">
+        {menuItems.map((item) => (
+          <li><a href={item.href} class="text-sm font-medium text-gray-600 hover:text-gray-900">{item.label}</a></li>
+        ))}
+      </ul>
+    )}
   </nav>
 </header>

package/templates/astro/src/content.config.ts

@@ -1,14 +1,21 @@
 import { defineCollection } from "astro:content";
 import { headroomLoader } from "@headroom-cms/api/astro";
 
+let schemas: Record<string, import("zod").ZodTypeAny> = {};
+try {
+  schemas = await import("./lib/schemas");
+} catch {
+  // schemas not yet generated — collections still work, just without validation
+}
+
 export const collections = {
   posts: defineCollection({
-    loader: headroomLoader({ collection: "posts" }),
+    loader: headroomLoader({ collection: "posts", schema: schemas.postsSchema }),
   }),
   pages: defineCollection({
-    loader: headroomLoader({ collection: "pages", bodies: true }),
+    loader: headroomLoader({ collection: "pages", bodies: true, schema: schemas.pagesSchema }),
   }),
   "site-settings": defineCollection({
-    loader: headroomLoader({ collection: "site-settings", bodies: true }),
+    loader: headroomLoader({ collection: "site-settings", bodies: true, schema: schemas.siteSettingsSchema }),
   }),
 };

package/templates/astro/src/pages/[...slug].astro

@@ -8,10 +8,12 @@ import { resolveContentLink } from "../lib/links";
 
 export async function getStaticPaths() {
   const pages = await getCollection("pages");
-  return pages.map((page) => ({
-    params: { slug: page.id },
-    props: { page },
-  }));
+  return pages
+    .filter((page) => page.id !== "home")
+    .map((page) => ({
+      params: { slug: page.id },
+      props: { page },
+    }));
 }
 
 const { page } = Astro.props;
@@ -23,7 +25,6 @@ const refs = (page.data._refs || {}) as RefsMap;
 <BaseLayout title={page.data.title}>
   <article class="py-12 px-6">
     <div class="max-w-3xl mx-auto">
-      <h1 class="text-4xl font-extrabold tracking-tight mb-8">{page.data.title}</h1>
       <div class="prose">
         <BlockRenderer blocks={blocks} refs={refs} resolveContentLink={resolveContentLink} />
       </div>

package/templates/astro/src/pages/index.astro

@@ -2,6 +2,9 @@
 import { getCollection, getEntry } from "astro:content";
 import BaseLayout from "../layouts/BaseLayout.astro";
 import PostCard from "../components/PostCard.astro";
+import BlockRenderer from "@headroom-cms/api/blocks/BlockRenderer.astro";
+import type { Block, RefsMap } from "@headroom-cms/api";
+import { resolveContentLink } from "../lib/links";
 
 const settingsEntry = await getEntry("site-settings", "site-settings");
 const siteName = (settingsEntry?.data.body?.siteName as string) || "My Site";
@@ -10,6 +13,11 @@ const tagline = (settingsEntry?.data.body?.tagline as string) || "";
 const posts = (await getCollection("posts"))
   .sort((a, b) => new Date(b.data.publishedAt).getTime() - new Date(a.data.publishedAt).getTime())
   .slice(0, 3);
+
+const pages = await getCollection("pages");
+const homePage = pages.find((page) => page.id === "home");
+const homeBlocks = (homePage?.data.body?.content || []) as Block[];
+const homeRefs = (homePage?.data._refs || {}) as RefsMap;
 ---
 
 <BaseLayout>
@@ -34,4 +42,12 @@ const posts = (await getCollection("posts"))
       </div>
     </section>
   )}
+
+  {homeBlocks.length > 0 && (
+    <section class="py-12 px-6">
+      <div class="max-w-3xl mx-auto prose">
+        <BlockRenderer blocks={homeBlocks} refs={homeRefs} resolveContentLink={resolveContentLink} />
+      </div>
+    </section>
+  )}
 </BaseLayout>

package/templates/astro/sst-env.d.ts

@@ -0,0 +1,10 @@
+/* This file is auto-generated by SST. Do not edit. */
+/* tslint:disable */
+/* eslint-disable */
+/* deno-fmt-ignore-file */
+/* biome-ignore-all lint: auto-generated */
+
+/// <reference path="../../../../sst-env.d.ts" />
+
+import "sst"
+export {}

package/templates/nextjs/CLAUDE.md

@@ -0,0 +1,394 @@
+# Headroom CMS - Next.js Site
+
+This is a Next.js site powered by [Headroom CMS](https://github.com/headroom-cms), a serverless headless CMS. Content is managed in the Headroom admin UI and fetched via the `@headroom-cms/api` SDK.
+
+## Tech Stack
+
+- **Next.js 15** (App Router, React Server Components)
+- **@headroom-cms/api** SDK for data fetching and block rendering
+- **Tailwind CSS v4** for styling
+
+## Project Structure
+
+```
+src/
+├── app/
+│   ├── layout.tsx           # Root layout with Header, Footer, metadata from site-settings
+│   ├── page.tsx             # Homepage
+│   ├── globals.css          # Tailwind imports
+│   ├── not-found.tsx        # 404 page
+│   ├── blog/
+│   │   ├── page.tsx         # Blog listing
+│   │   └── [slug]/page.tsx  # Blog post detail
+│   └── [slug]/page.tsx      # Dynamic pages from "pages" collection
+├── components/              # Reusable React components
+└── lib/
+    ├── client.ts            # Singleton HeadroomClient instance
+    └── links.ts             # Content link resolver (maps refs to URL paths)
+```
+
+## Environment Variables
+
+Copy `_env.example` to `.env.local` and fill in your Headroom credentials:
+
+```bash
+HEADROOM_URL=https://your-headroom-url.cloudfront.net
+HEADROOM_SITE=your-site.com
+HEADROOM_API_KEY=headroom_xxxxx
+HEADROOM_IMAGE_SIGNING_SECRET=your-secret  # optional, for image transforms
+```
+
+## Commands
+
+```bash
+npm run dev               # Start Next.js dev server
+npm run build             # Build for production
+npm run start             # Start production server
+npm run generate:schemas  # Generate Zod schemas from Headroom collections
+```
+
+## Default Collections
+
+New Headroom sites are scaffolded with three collections:
+
+| Collection | Type | Description |
+|------------|------|-------------|
+| `posts` | Standard | Blog posts with `author` (text) and `content` (blocks) fields; use the `featured` tag to mark featured posts |
+| `pages` | Standard | Generic pages with a `content` (blocks) field |
+| `site-settings` | Singleton | Site name, tagline, footer text, and menu items |
+
+## Fetching Data
+
+All data fetching uses the `HeadroomClient` from `src/lib/client.ts`. Since this is a Next.js App Router project, data fetching happens in **Server Components** (the default).
+
+### Getting the Client
+
+```tsx
+import { getClient } from "@/lib/client";
+
+export default async function MyPage() {
+  const client = getClient();
+  const { items: posts } = await client.listContent("posts", {
+    limit: 10,
+    sort: "published_desc",
+  });
+  // ...
+}
+```
+
+### SDK Client Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `listContent(collection, opts?)` | `{ items, cursor, hasMore }` | List published content with pagination/filtering |
+| `getContent(contentId)` | `ContentItem` | Get single item by ID (includes body + refs) |
+| `getContentBySlug(collection, slug)` | `ContentItem \| undefined` | Look up by slug |
+| `getSingleton(collection)` | `ContentItem` | Get singleton content (e.g. site settings) |
+| `listCollections()` | `{ items }` | List all collections |
+| `getCollection(name)` | `Collection` | Get collection schema |
+| `mediaUrl(path)` | `string` | Full URL for a media path |
+| `transformUrl(path, opts?)` | `string` | Signed image transform URL |
+
+### listContent Options
+
+```ts
+const { items, cursor, hasMore } = await client.listContent("posts", {
+  limit: 10,
+  cursor: "...",             // pagination
+  sort: "published_desc",    // published_desc | published_asc | title_asc | title_desc
+  before: 1700000000,        // unix timestamp filter
+  after: 1690000000,
+  relatedTo: "01ABC",        // reverse relationship query
+  relField: "author",        // filter reverse query to specific field
+});
+```
+
+### Static Generation
+
+Use `generateStaticParams` to pre-render content pages:
+
+```tsx
+export async function generateStaticParams() {
+  const client = getClient();
+  const { items } = await client.listContent("posts", { limit: 100 });
+  return items.map((post) => ({ slug: post.slug }));
+}
+```
+
+### Fetching Singleton Content
+
+Site-wide settings are stored in the `site-settings` singleton collection:
+
+```tsx
+const client = getClient();
+const settings = await client.getSingleton("site-settings").catch(() => null);
+const siteName = (settings?.body?.siteName as string) || "My Site";
+const menuItems = (settings?.body?.menuItems as Array<{ label: string; href: string }>) || [];
+```
+
+## Rendering Blocks
+
+Content bodies are arrays of [BlockNote](https://www.blocknotejs.org/) blocks. Use the React `BlockRenderer` component:
+
+```tsx
+import { BlockRenderer } from "@headroom-cms/api/react";
+import "@headroom-cms/api/react/headroom-blocks.css";
+import type { Block, RefsMap } from "@headroom-cms/api";
+import { resolveContentLink } from "@/lib/links";
+
+export default async function PostPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const client = getClient();
+  const post = await client.getContentBySlug("posts", slug);
+  if (!post) notFound();
+
+  const blocks = (post.body?.content || []) as Block[];
+  const refs = (post._refs || {}) as RefsMap;
+
+  return (
+    <div className="prose">
+      <BlockRenderer
+        blocks={blocks}
+        baseUrl={process.env.HEADROOM_URL}
+        refs={refs}
+        resolveContentLink={resolveContentLink}
+      />
+    </div>
+  );
+}
+```
+
+### BlockRenderer Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `blocks` | `Block[]` | Block content array from `post.body.content` |
+| `baseUrl` | `string?` | Base URL for media |
+| `refs` | `RefsMap?` | Content reference map from `post._refs` (resolves `headroom://` links) |
+| `resolveContentLink` | `(ref: PublicContentRef) => string` | Maps content references to URL paths |
+| `components` | `BlockComponentMap?` | Override or extend block component rendering |
+| `fallback` | `ComponentType \| null` | Custom fallback for unknown blocks (`null` to suppress) |
+| `className` | `string?` | CSS class for the wrapper `<div>` |
+
+### Block Types
+
+Built-in block types: `paragraph`, `heading`, `image`, `codeBlock`, `bulletListItem`, `numberedListItem`, `checkListItem`, `table`
+
+### Styling Blocks
+
+Import the default stylesheet:
+
+```tsx
+import "@headroom-cms/api/react/headroom-blocks.css";
+```
+
+Styles use low-specificity `:where()` selectors, easy to override. Customize via CSS custom properties:
+
+| Property | Default | Used by |
+|----------|---------|---------|
+| `--hr-code-bg` | `#f3f4f6` | Inline code background |
+| `--hr-link-color` | `#2563eb` | Link color |
+| `--hr-image-radius` | `0.5rem` | Image border radius |
+| `--hr-caption-color` | `#6b7280` | Image caption color |
+| `--hr-code-block-bg` | `#1e1e1e` | Code block background |
+| `--hr-code-block-color` | `#d4d4d4` | Code block text color |
+| `--hr-accent` | `#2563eb` | Checkbox accent color |
+| `--hr-table-header-bg` | `#f9fafb` | Table header background |
+
+### Custom Block Components
+
+Pass a `components` map to override built-in blocks or render custom block types:
+
+```tsx
+import { BlockRenderer } from "@headroom-cms/api/react";
+import type { BlockComponentProps } from "@headroom-cms/api/react";
+
+function Callout({ block }: BlockComponentProps) {
+  return (
+    <div className="bg-blue-50 border-l-4 border-blue-500 p-4 my-4">
+      <p>{block.props?.text as string}</p>
+    </div>
+  );
+}
+
+function CustomImage({ block }: BlockComponentProps) {
+  const src = block.props?.url as string;
+  return (
+    <figure className="my-8">
+      <img src={src} alt={block.props?.caption as string} className="rounded-xl shadow-lg" />
+    </figure>
+  );
+}
+
+<BlockRenderer
+  blocks={blocks}
+  baseUrl={process.env.HEADROOM_URL}
+  refs={refs}
+  resolveContentLink={resolveContentLink}
+  components={{
+    callout: Callout,
+    image: CustomImage,  // override built-in image rendering
+  }}
+/>
+```
+
+## Content Links
+
+Rich text can contain links to other Headroom content using `headroom://content/{collection}/{contentId}` URLs. The `_refs` map on each content item resolves these to metadata (slug, title, collection, published status).
+
+The `BlockRenderer` resolves these automatically using the `resolveContentLink` prop. Define your URL mapping in `src/lib/links.ts`:
+
+```ts
+import type { PublicContentRef } from "@headroom-cms/api";
+
+export function resolveContentLink(ref: PublicContentRef): string {
+  switch (ref.collection) {
+    case "posts":
+      return `/blog/${ref.slug}`;
+    default:
+      return `/${ref.slug}`;
+  }
+}
+```
+
+## Relationships
+
+Collections can define relationships to other collections. Access them on content items:
+
+```ts
+// Forward: get a project's related artists
+const project = await client.getContent("01ABC");
+const artists = project.relationships?.artists; // ContentRef[]
+
+// Reverse: find all projects referencing an artist
+const { items } = await client.listContent("projects", {
+  relatedTo: "01ARTIST",
+  relField: "artists",
+});
+```
+
+## Images and Media
+
+Media paths in content are relative (e.g., `/media/site/id/original.jpg`). Use the client to build full URLs:
+
+```ts
+const client = getClient();
+
+// Full URL for original image
+client.mediaUrl(post.coverUrl);
+
+// Signed transform URL (resized + webp)
+client.transformUrl(post.coverUrl, { width: 800, format: "webp" });
+```
+
+### Transform Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `width` | `number` | Target width in pixels |
+| `height` | `number` | Target height in pixels |
+| `fit` | `"cover" \| "contain" \| "fill" \| "inside" \| "outside"` | Resize fit mode |
+| `format` | `"webp" \| "avif" \| "jpeg" \| "png"` | Output format |
+| `quality` | `number` | 1-100 quality |
+
+Transforms require `HEADROOM_IMAGE_SIGNING_SECRET` in `.env.local`. Without it, `transformUrl()` falls back to `mediaUrl()`.
+
+## Adding a New Collection
+
+1. Create the collection in the Headroom admin UI
+2. Create pages under `src/app/`:
+   ```tsx
+   // src/app/projects/page.tsx — listing
+   import { getClient } from "@/lib/client";
+
+   export default async function ProjectsPage() {
+     const client = getClient();
+     const { items } = await client.listContent("projects", { sort: "published_desc" });
+     return (
+       <div className="max-w-5xl mx-auto py-12 px-6">
+         {items.map((project) => (
+           <a key={project.contentId} href={`/projects/${project.slug}`}>
+             <h3>{project.title}</h3>
+           </a>
+         ))}
+       </div>
+     );
+   }
+   ```
+   ```tsx
+   // src/app/projects/[slug]/page.tsx — detail
+   import { getClient } from "@/lib/client";
+   import { BlockRenderer } from "@headroom-cms/api/react";
+   import "@headroom-cms/api/react/headroom-blocks.css";
+   import { resolveContentLink } from "@/lib/links";
+   import { notFound } from "next/navigation";
+   import type { Block, RefsMap } from "@headroom-cms/api";
+
+   export async function generateStaticParams() {
+     const client = getClient();
+     const { items } = await client.listContent("projects", { limit: 100 });
+     return items.map((p) => ({ slug: p.slug }));
+   }
+
+   export default async function ProjectPage({ params }: { params: Promise<{ slug: string }> }) {
+     const { slug } = await params;
+     const client = getClient();
+     const project = await client.getContentBySlug("projects", slug);
+     if (!project) notFound();
+
+     const blocks = (project.body?.content || []) as Block[];
+     const refs = (project._refs || {}) as RefsMap;
+
+     return (
+       <article className="py-12 px-6">
+         <div className="max-w-3xl mx-auto">
+           <h1 className="text-4xl font-extrabold tracking-tight mb-4">{project.title}</h1>
+           <div className="prose">
+             <BlockRenderer blocks={blocks} baseUrl={process.env.HEADROOM_URL} refs={refs} resolveContentLink={resolveContentLink} />
+           </div>
+         </div>
+       </article>
+     );
+   }
+   ```
+3. Update `src/lib/links.ts` to map the new collection to URL paths
+
+## Error Handling
+
+```ts
+import { HeadroomClient, HeadroomError } from "@headroom-cms/api";
+
+try {
+  const post = await client.getContent("nonexistent");
+} catch (e) {
+  if (e instanceof HeadroomError) {
+    console.log(e.status); // 404
+    console.log(e.code);   // "CONTENT_NOT_FOUND"
+  }
+}
+```
+
+## Key Types
+
+```ts
+import type {
+  ContentItem,        // Full content item with body, refs, relationships
+  ContentMetadata,    // Content without body (listings)
+  Block,              // A BlockNote block
+  RefsMap,            // Map of content ID -> PublicContentRef
+  PublicContentRef,   // { contentId, collection, slug, title, published }
+  ContentRef,         // Relationship reference
+  Collection,         // Collection schema
+  FieldDef,           // Field definition in a collection
+  RelationshipDef,    // Relationship definition
+  HeadroomConfig,     // Client configuration
+  TransformOptions,   // Image transform options
+} from "@headroom-cms/api";
+
+// React-specific types
+import type {
+  BlockRendererProps,
+  BlockComponentProps,
+  BlockComponentMap,
+} from "@headroom-cms/api/react";
+```

package/templates/nextjs/package.json

@@ -5,17 +5,19 @@
   "scripts": {
     "dev": "next dev",
     "build": "next build",
-    "start": "next start"
+    "start": "next start",
+    "generate:schemas": "bash scripts/generate-schemas.sh"
   },
   "dependencies": {
     "next": "^15.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@headroom-cms/api": "^0.1.3"
+    "@headroom-cms/api": "^0.1.4"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.0.0",
     "tailwindcss": "^4.0.0",
+    "tsx": "^4.0.0",
     "typescript": "^5.9.3",
     "@types/react": "^19.0.0",
     "@types/node": "^22.0.0"

package/templates/nextjs/scripts/generate-schemas.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Generates Zod schemas from Headroom collection definitions.
+# Requires: .env with HEADROOM_* vars, API accessible.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SITE_DIR="$(dirname "$SCRIPT_DIR")"
+
+if [ ! -f "$SITE_DIR/.env" ]; then
+  echo "Error: .env not found. Create a .env file with HEADROOM_URL, HEADROOM_SITE, and HEADROOM_API_KEY." >&2
+  exit 1
+fi
+
+cd "$SITE_DIR"
+npx tsx scripts/generate-schemas.ts

package/templates/nextjs/scripts/generate-schemas.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env tsx
+/**
+ * Generates Zod schemas from Headroom collection definitions.
+ * Reads connection details from .env and writes src/lib/schemas.ts.
+ *
+ * Usage: npx tsx scripts/generate-schemas.ts
+ */
+
+import { writeFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { HeadroomClient } from "@headroom-cms/api";
+import { generateZodSchemas } from "@headroom-cms/api/codegen";
+import { configFromEnv } from "@headroom-cms/api/astro";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const siteDir = resolve(__dirname, "..");
+
+const config = configFromEnv();
+if (!config.site || !config.apiKey) {
+  console.error("Error: HEADROOM_SITE and HEADROOM_API_KEY must be set in .env");
+  process.exit(1);
+}
+
+const client = new HeadroomClient(config);
+const output = await generateZodSchemas(client);
+
+const outPath = resolve(siteDir, "src/lib/schemas.ts");
+writeFileSync(outPath, output, "utf-8");
+console.log(`Schemas generated at src/lib/schemas.ts`);

package/templates/nextjs/src/app/[slug]/page.tsx

@@ -12,7 +12,9 @@ interface Props {
 export async function generateStaticParams() {
   const client = getClient();
   const { items } = await client.listContent("pages", { limit: 100 });
-  return items.map((page) => ({ slug: page.slug }));
+  return items
+    .filter((page) => page.slug !== "home")
+    .map((page) => ({ slug: page.slug }));
 }
 
 export default async function Page({ params }: Props) {
@@ -27,9 +29,6 @@ export default async function Page({ params }: Props) {
   return (
     <article className="py-12 px-6">
       <div className="max-w-3xl mx-auto">
-        <h1 className="text-4xl font-extrabold tracking-tight mb-8">
-          {page.title}
-        </h1>
         <div className="prose">
           <BlockRenderer
             blocks={blocks}

package/templates/nextjs/src/app/page.tsx

@@ -1,5 +1,9 @@
 import { getClient } from "@/lib/client";
 import { PostCard } from "@/components/PostCard";
+import { BlockRenderer } from "@headroom-cms/api/react";
+import "@headroom-cms/api/react/headroom-blocks.css";
+import { resolveContentLink } from "@/lib/links";
+import type { Block, RefsMap } from "@headroom-cms/api";
 
 export default async function Home() {
   const client = getClient();
@@ -8,6 +12,9 @@ export default async function Home() {
     limit: 3,
     sort: "published_desc",
   });
+  const homePage = await client.getContentBySlug("pages", "home").catch(() => null);
+  const homeBlocks = (homePage?.body?.content || []) as Block[];
+  const homeRefs = (homePage?._refs || {}) as RefsMap;
 
   return (
     <>
@@ -36,6 +43,19 @@ export default async function Home() {
           </div>
         </section>
       )}
+
+      {homeBlocks.length > 0 && (
+        <section className="py-12 px-6">
+          <div className="max-w-3xl mx-auto prose">
+            <BlockRenderer
+              blocks={homeBlocks}
+              baseUrl={process.env.HEADROOM_URL}
+              refs={homeRefs}
+              resolveContentLink={resolveContentLink}
+            />
+          </div>
+        </section>
+      )}
     </>
   );
 }

package/templates/nextjs/src/components/Footer.tsx

@@ -1,7 +1,14 @@
-export function Footer() {
+import { getClient } from "@/lib/client";
+
+export async function Footer() {
+  const client = getClient();
+  const settings = await client.getSingleton("site-settings").catch(() => null);
+  const footerText = (settings?.body?.footerText as string) || "";
+
   return (
     <footer className="border-t border-gray-100 py-8 mt-16">
       <div className="max-w-5xl mx-auto px-6 text-center text-sm text-gray-500">
+        {footerText && <p className="mb-2">{footerText}</p>}
         <p>
           Powered by{" "}
           <a href="https://headroom.dev" className="hover:underline">Headroom CMS</a>

package/templates/nextjs/src/components/Header.tsx

@@ -5,6 +5,7 @@ export async function Header() {
   const client = getClient();
   const settings = await client.getSingleton("site-settings").catch(() => null);
   const siteName = (settings?.body?.siteName as string) || "My Site";
+  const menuItems = (settings?.body?.menuItems as Array<{ label: string; href: string }>) || [];
 
   return (
     <header className="border-b border-gray-100 bg-white sticky top-0 z-50">
@@ -12,10 +13,13 @@ export async function Header() {
         <Link href="/" className="text-xl font-bold tracking-tight hover:opacity-80 transition-opacity">
           {siteName}
         </Link>
-        <ul className="flex items-center gap-6">
-          <li><Link href="/" className="text-sm font-medium text-gray-600 hover:text-gray-900">Home</Link></li>
-          <li><Link href="/blog" className="text-sm font-medium text-gray-600 hover:text-gray-900">Blog</Link></li>
-        </ul>
+        {menuItems.length > 0 && (
+          <ul className="flex items-center gap-6">
+            {menuItems.map((item) => (
+              <li key={item.href}><Link href={item.href} className="text-sm font-medium text-gray-600 hover:text-gray-900">{item.label}</Link></li>
+            ))}
+          </ul>
+        )}
       </nav>
     </header>
   );

package/templates/nextjs/sst-env.d.ts

@@ -0,0 +1,10 @@
+/* This file is auto-generated by SST. Do not edit. */
+/* tslint:disable */
+/* eslint-disable */
+/* deno-fmt-ignore-file */
+/* biome-ignore-all lint: auto-generated */
+
+/// <reference path="../../../../sst-env.d.ts" />
+
+import "sst"
+export {}