create-headroom-site 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/** Dotfiles are stored with _ prefix to survive npm publish, renamed on copy */
+declare const RENAME_MAP: Record<string, string>;
+/** Recursively copy a directory, skipping node_modules/.git, renaming _ dotfiles */
+declare function copyDir(src: string, dest: string): void;
+/** Generate .env file content from answers */
+declare function generateEnv(answers: {
+    url: string;
+    site: string;
+    apiKey: string;
+    imageSigningSecret?: string;
+}): string;
+/** Patch package.json name to match chosen directory */
+declare function patchPackageName(targetDir: string, directory: string): void;
+
+export { RENAME_MAP, copyDir, generateEnv, patchPackageName };

package/dist/index.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+var TEMPLATES_DIR = path.resolve(__dirname, "..", "templates");
+var RENAME_MAP = {
+  _gitignore: ".gitignore",
+  "_env.example": ".env.example"
+};
+async function main() {
+  const argDir = process.argv[2];
+  p.intro("create-headroom-site");
+  const answers = await p.group(
+    {
+      directory: () => argDir ? Promise.resolve(argDir) : p.text({
+        message: "Project directory",
+        initialValue: "my-headroom-site",
+        validate: (v) => v.trim().length === 0 ? "Directory name is required" : void 0
+      }),
+      framework: () => p.select({
+        message: "Framework",
+        options: [
+          { label: "Astro", value: "astro" },
+          { label: "Next.js", value: "nextjs" }
+        ]
+      }),
+      url: () => p.text({
+        message: "Headroom URL (your CDN URL, e.g. https://headroom.example.com)",
+        validate: (v) => {
+          const trimmed = v.trim();
+          if (trimmed.length === 0) return "URL is required";
+          if (!/^https?:\/\/.+/.test(trimmed))
+            return "URL must start with https:// or http://";
+          if (trimmed.endsWith("/"))
+            return "URL must not end with a trailing slash";
+          return void 0;
+        }
+      }),
+      site: () => p.text({
+        message: "Site identifier (e.g. mysite.com)",
+        validate: (v) => v.trim().length === 0 ? "Site identifier is required" : void 0
+      }),
+      apiKey: () => p.text({
+        message: "API key",
+        validate: (v) => v.trim().length === 0 ? "API key is required" : void 0
+      }),
+      imageSigningSecret: () => p.text({
+        message: "Image signing secret (optional, for transforms)",
+        defaultValue: ""
+      })
+    },
+    { onCancel: () => process.exit(1) }
+  );
+  const targetDir = path.resolve(process.cwd(), answers.directory);
+  if (fs.existsSync(targetDir)) {
+    const files = fs.readdirSync(targetDir);
+    if (files.length > 0) {
+      p.cancel(`Directory ${answers.directory} is not empty`);
+      process.exit(1);
+    }
+  }
+  const verifySpinner = p.spinner();
+  verifySpinner.start("Verifying API credentials...");
+  try {
+    const res = await fetch(`${answers.url.replace(/\/$/, "")}/health`);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    verifySpinner.stop("Connected to " + answers.url);
+  } catch {
+    verifySpinner.stop(
+      pc.yellow("\u26A0 Could not reach API \u2014 continuing anyway (check .env later)")
+    );
+  }
+  const templateDir = path.join(TEMPLATES_DIR, answers.framework);
+  copyDir(templateDir, targetDir);
+  p.log.success(`Created ${pc.bold(answers.directory)}/`);
+  const envContent = generateEnv(answers);
+  fs.writeFileSync(path.join(targetDir, ".env"), envContent);
+  p.log.success("Wrote .env");
+  patchPackageName(targetDir, answers.directory);
+  p.outro(`Done! Next steps:
+  ${pc.cyan("cd")} ${answers.directory}
+  ${pc.cyan("npm install")}
+  ${pc.cyan("npm run dev")}`);
+}
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name === "node_modules" || entry.name === ".git") continue;
+    const srcPath = path.join(src, entry.name);
+    const destName = RENAME_MAP[entry.name] || entry.name;
+    const destPath = path.join(dest, destName);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+function generateEnv(answers) {
+  const url = answers.url.replace(/\/+$/, "");
+  const lines = [
+    `HEADROOM_URL=${url}`,
+    `HEADROOM_SITE=${answers.site}`,
+    `HEADROOM_API_KEY=${answers.apiKey}`
+  ];
+  if (answers.imageSigningSecret)
+    lines.push(
+      `HEADROOM_IMAGE_SIGNING_SECRET=${answers.imageSigningSecret}`
+    );
+  lines.push("");
+  return lines.join("\n");
+}
+function patchPackageName(targetDir, directory) {
+  const pkgPath = path.join(targetDir, "package.json");
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+  pkg.name = path.basename(directory);
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+export {
+  RENAME_MAP,
+  copyDir,
+  generateEnv,
+  patchPackageName
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "create-headroom-site",
+  "version": "0.1.3",
+  "description": "Scaffold a new Headroom CMS frontend site (Astro or Next.js)",
+  "type": "module",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "bin": {
+    "create-headroom-site": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --outDir dist",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "tsup": "~8.5.0",
+    "typescript": "~5.9.3",
+    "@types/node": "~22.0.0",
+    "vitest": "^3.2.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/astro/_env.example

@@ -0,0 +1,4 @@
+HEADROOM_URL=https://your-headroom-url.cloudfront.net
+HEADROOM_SITE=your-site.com
+HEADROOM_API_KEY=headroom_xxxxx
+HEADROOM_IMAGE_SIGNING_SECRET=your-secret

package/templates/astro/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.astro/
+.env

package/templates/astro/astro.config.mjs

@@ -0,0 +1,11 @@
+import { defineConfig } from "astro/config";
+import tailwindcss from "@tailwindcss/vite";
+import { headroomDevRefresh } from "@headroom-cms/api/astro";
+
+export default defineConfig({
+  output: "static",
+  integrations: [headroomDevRefresh()],
+  vite: {
+    plugins: [tailwindcss()],
+  },
+});

package/templates/astro/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "my-headroom-site",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "astro": "^5.0.0",
+    "@headroom-cms/api": "^0.1.3"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.0",
+    "tailwindcss": "^4.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/astro/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="6" fill="#4338ca"/>
+  <text x="16" y="23" font-family="system-ui, sans-serif" font-size="20" font-weight="bold" fill="white" text-anchor="middle">H</text>
+</svg>

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

@@ -0,0 +1,8 @@
+<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">
+    <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>
+    </p>
+  </div>
+</footer>

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

@@ -0,0 +1,18 @@
+---
+import { getEntry } from "astro:content";
+
+const settingsEntry = await getEntry("site-settings", "site-settings");
+const siteName = (settingsEntry?.data.body?.siteName as string) || "My Site";
+---
+
+<header class="border-b border-gray-100 bg-white sticky top-0 z-50">
+  <nav class="max-w-5xl mx-auto px-6 py-4 flex items-center justify-between">
+    <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>
+  </nav>
+</header>

package/templates/astro/src/components/PostCard.astro

@@ -0,0 +1,16 @@
+---
+interface Props {
+  title: string;
+  snippet?: string;
+  slug: string;
+}
+
+const { title, snippet, slug } = Astro.props;
+---
+
+<a href={`/blog/${slug}`} class="block group">
+  <article class="bg-white rounded-lg border border-gray-100 p-6 transition-shadow hover:shadow-md">
+    <h3 class="text-lg font-semibold group-hover:text-primary transition-colors">{title}</h3>
+    {snippet && <p class="mt-2 text-sm text-gray-500 line-clamp-2">{snippet}</p>}
+  </article>
+</a>

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

@@ -0,0 +1,14 @@
+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 }),
+  }),
+  "site-settings": defineCollection({
+    loader: headroomLoader({ collection: "site-settings", bodies: true }),
+  }),
+};

package/templates/astro/src/env.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="astro/client" />
+
+interface ImportMetaEnv {
+  readonly HEADROOM_URL: string;
+  readonly HEADROOM_SITE: string;
+  readonly HEADROOM_API_KEY: string;
+  readonly HEADROOM_IMAGE_SIGNING_SECRET: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/templates/astro/src/layouts/BaseLayout.astro

@@ -0,0 +1,36 @@
+---
+import { getEntry } from "astro:content";
+import Header from "../components/Header.astro";
+import Footer from "../components/Footer.astro";
+import "../styles/global.css";
+
+interface Props {
+  title?: string;
+  description?: string;
+}
+
+const settingsEntry = await getEntry("site-settings", "site-settings");
+const siteName = (settingsEntry?.data.body?.siteName as string) || "My Site";
+const defaultDescription = (settingsEntry?.data.body?.tagline as string) || "";
+
+const { title, description = defaultDescription } = Astro.props;
+const fullTitle = title ? `${title} | ${siteName}` : siteName;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content={description} />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <title>{fullTitle}</title>
+  </head>
+  <body class="min-h-screen flex flex-col">
+    <Header />
+    <main class="flex-1">
+      <slot />
+    </main>
+    <Footer />
+  </body>
+</html>

package/templates/astro/src/lib/client.ts

@@ -0,0 +1,16 @@
+import { HeadroomClient } from "@headroom-cms/api";
+
+let _client: HeadroomClient | null = null;
+
+export function getClient(): HeadroomClient {
+  if (!_client) {
+    _client = new HeadroomClient({
+      url: import.meta.env.HEADROOM_URL || "http://localhost:3000",
+      site: import.meta.env.HEADROOM_SITE || "my.local",
+      apiKey: import.meta.env.HEADROOM_API_KEY || "",
+      imageSigningSecret:
+        import.meta.env.HEADROOM_IMAGE_SIGNING_SECRET || undefined,
+    });
+  }
+  return _client;
+}

package/templates/astro/src/lib/links.ts

@@ -0,0 +1,11 @@
+import type { PublicContentRef } from "@headroom-cms/api";
+
+/** Map a content reference to its URL path. */
+export function resolveContentLink(ref: PublicContentRef): string {
+  switch (ref.collection) {
+    case "posts":
+      return `/blog/${ref.slug}`;
+    default:
+      return `/${ref.slug}`;
+  }
+}

package/templates/astro/src/pages/404.astro

@@ -0,0 +1,13 @@
+---
+import BaseLayout from "../layouts/BaseLayout.astro";
+---
+
+<BaseLayout title="Page Not Found">
+  <section class="py-20 px-6 text-center">
+    <div class="max-w-3xl mx-auto">
+      <h1 class="text-6xl font-extrabold tracking-tight text-gray-300">404</h1>
+      <p class="mt-4 text-xl text-gray-500">Page not found</p>
+      <a href="/" class="mt-8 inline-block text-sm font-medium hover:underline">&larr; Back to home</a>
+    </div>
+  </section>
+</BaseLayout>

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

@@ -0,0 +1,32 @@
+---
+import { getCollection } from "astro:content";
+import BaseLayout from "../layouts/BaseLayout.astro";
+import BlockRenderer from "@headroom-cms/api/blocks/BlockRenderer.astro";
+import type { Block, RefsMap } from "@headroom-cms/api";
+import { getClient } from "../lib/client";
+import { resolveContentLink } from "../lib/links";
+
+export async function getStaticPaths() {
+  const pages = await getCollection("pages");
+  return pages.map((page) => ({
+    params: { slug: page.id },
+    props: { page },
+  }));
+}
+
+const { page } = Astro.props;
+const client = getClient();
+const blocks = (page.data.body?.content || []) as Block[];
+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>
+    </div>
+  </article>
+</BaseLayout>

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

@@ -0,0 +1,38 @@
+---
+import { getCollection } from "astro:content";
+import BaseLayout from "../../layouts/BaseLayout.astro";
+import BlockRenderer from "@headroom-cms/api/blocks/BlockRenderer.astro";
+import type { Block, RefsMap } from "@headroom-cms/api";
+import { getClient } from "../../lib/client";
+import { resolveContentLink } from "../../lib/links";
+
+export async function getStaticPaths() {
+  const posts = await getCollection("posts");
+  return posts.map((post) => ({
+    params: { slug: post.id },
+    props: { post },
+  }));
+}
+
+const { post } = Astro.props;
+const client = getClient();
+const fullPost = await client.getContentBySlug("posts", post.id);
+if (!fullPost) return Astro.redirect("/404");
+
+const blocks = (fullPost.body?.content || []) as Block[];
+const refs = (fullPost._refs || {}) as RefsMap;
+---
+
+<BaseLayout title={post.data.title} description={post.data.snippet}>
+  <article class="py-12 px-6">
+    <div class="max-w-3xl mx-auto">
+      <h1 class="text-4xl font-extrabold tracking-tight mb-4">{post.data.title}</h1>
+      <div class="prose">
+        <BlockRenderer blocks={blocks} refs={refs} resolveContentLink={resolveContentLink} />
+      </div>
+      <footer class="mt-12 pt-8 border-t border-gray-100">
+        <a href="/blog" class="text-sm font-medium hover:underline">&larr; Back to all posts</a>
+      </footer>
+    </div>
+  </article>
+</BaseLayout>

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

@@ -0,0 +1,25 @@
+---
+import { getCollection } from "astro:content";
+import BaseLayout from "../../layouts/BaseLayout.astro";
+import PostCard from "../../components/PostCard.astro";
+
+const posts = (await getCollection("posts"))
+  .sort((a, b) => new Date(b.data.publishedAt).getTime() - new Date(a.data.publishedAt).getTime());
+---
+
+<BaseLayout title="Blog">
+  <section class="py-12 px-6">
+    <div class="max-w-5xl mx-auto">
+      <h1 class="text-4xl font-extrabold tracking-tight mb-8">Blog</h1>
+      {posts.length > 0 ? (
+        <div class="grid md:grid-cols-3 gap-8">
+          {posts.map((post) => (
+            <PostCard title={post.data.title} snippet={post.data.snippet} slug={post.id} />
+          ))}
+        </div>
+      ) : (
+        <p class="text-gray-500">No posts yet. Create some content in the Headroom admin.</p>
+      )}
+    </div>
+  </section>
+</BaseLayout>

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

@@ -0,0 +1,37 @@
+---
+import { getCollection, getEntry } from "astro:content";
+import BaseLayout from "../layouts/BaseLayout.astro";
+import PostCard from "../components/PostCard.astro";
+
+const settingsEntry = await getEntry("site-settings", "site-settings");
+const siteName = (settingsEntry?.data.body?.siteName as string) || "My Site";
+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);
+---
+
+<BaseLayout>
+  <section class="py-20 px-6">
+    <div class="max-w-5xl mx-auto text-center">
+      <h1 class="text-5xl font-extrabold tracking-tight">{siteName}</h1>
+      {tagline && (
+        <p class="mt-4 text-xl text-gray-500 max-w-2xl mx-auto">{tagline}</p>
+      )}
+    </div>
+  </section>
+
+  {posts.length > 0 && (
+    <section class="py-12 px-6 bg-gray-50">
+      <div class="max-w-5xl mx-auto">
+        <h2 class="text-2xl font-bold mb-8">Recent Posts</h2>
+        <div class="grid md:grid-cols-3 gap-8">
+          {posts.map((post) => (
+            <PostCard title={post.data.title} snippet={post.data.snippet} slug={post.id} />
+          ))}
+        </div>
+      </div>
+    </section>
+  )}
+</BaseLayout>

package/templates/astro/src/styles/global.css

@@ -0,0 +1,137 @@
+@import "tailwindcss";
+
+@theme {
+  --color-primary: oklch(0.45 0.2 260);
+  --color-primary-light: oklch(0.55 0.18 260);
+  --color-accent: oklch(0.7 0.18 50);
+  --color-accent-dark: oklch(0.6 0.18 50);
+  --color-surface: oklch(0.98 0.005 80);
+  --color-surface-alt: oklch(0.95 0.01 80);
+  --color-text: oklch(0.25 0.02 260);
+  --color-text-muted: oklch(0.5 0.02 260);
+  --font-sans: "Inter", system-ui, -apple-system, sans-serif;
+  --font-display: "Inter", system-ui, -apple-system, sans-serif;
+}
+
+body {
+  font-family: var(--font-sans);
+  color: var(--color-text);
+  background: white;
+}
+
+/* Prose styles for block content */
+.prose h1 {
+  font-size: 2.25rem;
+  font-weight: 800;
+  line-height: 1.2;
+  margin-top: 2rem;
+  margin-bottom: 1rem;
+  letter-spacing: -0.02em;
+}
+
+.prose h2 {
+  font-size: 1.5rem;
+  font-weight: 700;
+  line-height: 1.3;
+  margin-top: 1.75rem;
+  margin-bottom: 0.75rem;
+}
+
+.prose h3 {
+  font-size: 1.25rem;
+  font-weight: 600;
+  line-height: 1.4;
+  margin-top: 1.5rem;
+  margin-bottom: 0.5rem;
+}
+
+.prose p {
+  margin-bottom: 1rem;
+  line-height: 1.75;
+}
+
+.prose ul,
+.prose ol {
+  margin-bottom: 1rem;
+  padding-left: 1.5rem;
+}
+
+.prose li {
+  margin-bottom: 0.25rem;
+  line-height: 1.75;
+}
+
+.prose ul li {
+  list-style-type: disc;
+}
+
+.prose ol li {
+  list-style-type: decimal;
+}
+
+.prose img {
+  border-radius: 0.5rem;
+  margin: 1.5rem auto;
+}
+
+.prose pre {
+  background: oklch(0.2 0.02 260);
+  color: oklch(0.9 0.01 80);
+  padding: 1rem 1.25rem;
+  border-radius: 0.5rem;
+  overflow-x: auto;
+  margin-bottom: 1rem;
+  font-size: 0.875rem;
+  line-height: 1.6;
+}
+
+.prose code {
+  font-family: ui-monospace, "Cascadia Code", "Fira Code", monospace;
+}
+
+.prose a {
+  color: var(--color-primary);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.prose a:hover {
+  color: var(--color-primary-light);
+}
+
+.prose blockquote {
+  border-left: 3px solid var(--color-primary);
+  padding-left: 1rem;
+  margin: 1rem 0;
+  color: var(--color-text-muted);
+  font-style: italic;
+}
+
+.prose figure {
+  margin: 1.5rem 0;
+  text-align: center;
+}
+
+.prose figcaption {
+  font-size: 0.875rem;
+  color: var(--color-text-muted);
+  margin-top: 0.5rem;
+}
+
+.prose table {
+  width: 100%;
+  border-collapse: collapse;
+  margin-bottom: 1rem;
+}
+
+.prose th,
+.prose td {
+  border: 1px solid oklch(0.85 0.01 80);
+  padding: 0.5rem 0.75rem;
+  text-align: left;
+}
+
+.prose th {
+  background: var(--color-surface-alt);
+  font-weight: 600;
+}

package/templates/astro/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  }
+}

package/templates/nextjs/_env.example

@@ -0,0 +1,4 @@
+HEADROOM_URL=https://your-headroom-url.cloudfront.net
+HEADROOM_SITE=your-site.com
+HEADROOM_API_KEY=headroom_xxxxx
+HEADROOM_IMAGE_SIGNING_SECRET=your-secret

package/templates/nextjs/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+.next/
+out/
+.env

package/templates/nextjs/next.config.ts

@@ -0,0 +1,14 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  images: {
+    remotePatterns: [
+      {
+        protocol: "https",
+        hostname: "**.cloudfront.net",
+      },
+    ],
+  },
+};
+
+export default nextConfig;

package/templates/nextjs/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "my-headroom-site",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@headroom-cms/api": "^0.1.3"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.0.0",
+    "tailwindcss": "^4.0.0",
+    "typescript": "^5.9.3",
+    "@types/react": "^19.0.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/templates/nextjs/postcss.config.mjs

@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};

package/templates/nextjs/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="6" fill="#4338ca"/>
+  <text x="16" y="23" font-family="system-ui, sans-serif" font-size="20" font-weight="bold" fill="white" text-anchor="middle">H</text>
+</svg>

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

@@ -0,0 +1,44 @@
+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";
+
+interface Props {
+  params: Promise<{ slug: string }>;
+}
+
+export async function generateStaticParams() {
+  const client = getClient();
+  const { items } = await client.listContent("pages", { limit: 100 });
+  return items.map((page) => ({ slug: page.slug }));
+}
+
+export default async function Page({ params }: Props) {
+  const { slug } = await params;
+  const client = getClient();
+  const page = await client.getContentBySlug("pages", slug);
+  if (!page) notFound();
+
+  const blocks = (page.body?.content || []) as Block[];
+  const refs = (page._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-8">
+          {page.title}
+        </h1>
+        <div className="prose">
+          <BlockRenderer
+            blocks={blocks}
+            baseUrl={process.env.HEADROOM_URL}
+            refs={refs}
+            resolveContentLink={resolveContentLink}
+          />
+        </div>
+      </div>
+    </article>
+  );
+}

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

@@ -0,0 +1,44 @@
+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";
+
+interface Props {
+  params: Promise<{ slug: string }>;
+}
+
+export async function generateStaticParams() {
+  const client = getClient();
+  const { items } = await client.listContent("posts", { limit: 100 });
+  return items.map((post) => ({ slug: post.slug }));
+}
+
+export default async function BlogPost({ params }: Props) {
+  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 (
+    <article className="py-12 px-6">
+      <div className="max-w-3xl mx-auto">
+        <h1 className="text-4xl font-extrabold tracking-tight mb-4">
+          {post.title}
+        </h1>
+        <div className="prose">
+          <BlockRenderer
+            blocks={blocks}
+            baseUrl={process.env.HEADROOM_URL}
+            refs={refs}
+            resolveContentLink={resolveContentLink}
+          />
+        </div>
+      </div>
+    </article>
+  );
+}

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

@@ -0,0 +1,27 @@
+import { getClient } from "@/lib/client";
+import { PostCard } from "@/components/PostCard";
+
+export default async function BlogIndex() {
+  const client = getClient();
+  const { items: posts } = await client.listContent("posts", {
+    limit: 100,
+    sort: "published_desc",
+  });
+
+  return (
+    <section className="py-12 px-6">
+      <div className="max-w-5xl mx-auto">
+        <h1 className="text-4xl font-extrabold tracking-tight mb-8">Blog</h1>
+        {posts.length > 0 ? (
+          <div className="grid md:grid-cols-3 gap-8">
+            {posts.map((post) => (
+              <PostCard key={post.contentId} title={post.title} snippet={post.snippet} slug={post.slug} />
+            ))}
+          </div>
+        ) : (
+          <p className="text-gray-500">No posts yet. Create some content in the Headroom admin.</p>
+        )}
+      </div>
+    </section>
+  );
+}

package/templates/nextjs/src/app/globals.css

@@ -0,0 +1,137 @@
+@import "tailwindcss";
+
+@theme {
+  --color-primary: oklch(0.45 0.2 260);
+  --color-primary-light: oklch(0.55 0.18 260);
+  --color-accent: oklch(0.7 0.18 50);
+  --color-accent-dark: oklch(0.6 0.18 50);
+  --color-surface: oklch(0.98 0.005 80);
+  --color-surface-alt: oklch(0.95 0.01 80);
+  --color-text: oklch(0.25 0.02 260);
+  --color-text-muted: oklch(0.5 0.02 260);
+  --font-sans: "Inter", system-ui, -apple-system, sans-serif;
+  --font-display: "Inter", system-ui, -apple-system, sans-serif;
+}
+
+body {
+  font-family: var(--font-sans);
+  color: var(--color-text);
+  background: white;
+}
+
+/* Prose styles for block content */
+.prose h1 {
+  font-size: 2.25rem;
+  font-weight: 800;
+  line-height: 1.2;
+  margin-top: 2rem;
+  margin-bottom: 1rem;
+  letter-spacing: -0.02em;
+}
+
+.prose h2 {
+  font-size: 1.5rem;
+  font-weight: 700;
+  line-height: 1.3;
+  margin-top: 1.75rem;
+  margin-bottom: 0.75rem;
+}
+
+.prose h3 {
+  font-size: 1.25rem;
+  font-weight: 600;
+  line-height: 1.4;
+  margin-top: 1.5rem;
+  margin-bottom: 0.5rem;
+}
+
+.prose p {
+  margin-bottom: 1rem;
+  line-height: 1.75;
+}
+
+.prose ul,
+.prose ol {
+  margin-bottom: 1rem;
+  padding-left: 1.5rem;
+}
+
+.prose li {
+  margin-bottom: 0.25rem;
+  line-height: 1.75;
+}
+
+.prose ul li {
+  list-style-type: disc;
+}
+
+.prose ol li {
+  list-style-type: decimal;
+}
+
+.prose img {
+  border-radius: 0.5rem;
+  margin: 1.5rem auto;
+}
+
+.prose pre {
+  background: oklch(0.2 0.02 260);
+  color: oklch(0.9 0.01 80);
+  padding: 1rem 1.25rem;
+  border-radius: 0.5rem;
+  overflow-x: auto;
+  margin-bottom: 1rem;
+  font-size: 0.875rem;
+  line-height: 1.6;
+}
+
+.prose code {
+  font-family: ui-monospace, "Cascadia Code", "Fira Code", monospace;
+}
+
+.prose a {
+  color: var(--color-primary);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.prose a:hover {
+  color: var(--color-primary-light);
+}
+
+.prose blockquote {
+  border-left: 3px solid var(--color-primary);
+  padding-left: 1rem;
+  margin: 1rem 0;
+  color: var(--color-text-muted);
+  font-style: italic;
+}
+
+.prose figure {
+  margin: 1.5rem 0;
+  text-align: center;
+}
+
+.prose figcaption {
+  font-size: 0.875rem;
+  color: var(--color-text-muted);
+  margin-top: 0.5rem;
+}
+
+.prose table {
+  width: 100%;
+  border-collapse: collapse;
+  margin-bottom: 1rem;
+}
+
+.prose th,
+.prose td {
+  border: 1px solid oklch(0.85 0.01 80);
+  padding: 0.5rem 0.75rem;
+  text-align: left;
+}
+
+.prose th {
+  background: var(--color-surface-alt);
+  font-weight: 600;
+}

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

@@ -0,0 +1,41 @@
+import type { Metadata } from "next";
+import { Header } from "@/components/Header";
+import { Footer } from "@/components/Footer";
+import { getClient } from "@/lib/client";
+import { unstable_cache } from "next/cache";
+import "./globals.css";
+
+const getSettings = unstable_cache(
+  async () => {
+    const client = getClient();
+    return client.getSingleton("site-settings");
+  },
+  ["site-settings"],
+  { revalidate: 3600 }
+);
+
+export async function generateMetadata(): Promise<Metadata> {
+  try {
+    const settings = await getSettings();
+    const siteName = (settings.body?.siteName as string) || "My Site";
+    return {
+      title: { default: siteName, template: `%s | ${siteName}` },
+      description: (settings.body?.tagline as string) || "",
+    };
+  } catch {
+    console.warn("Could not fetch site settings for metadata");
+    return { title: "My Site" };
+  }
+}
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body className="min-h-screen flex flex-col">
+        <Header />
+        <main className="flex-1">{children}</main>
+        <Footer />
+      </body>
+    </html>
+  );
+}

package/templates/nextjs/src/app/not-found.tsx

@@ -0,0 +1,15 @@
+import Link from "next/link";
+
+export default function NotFound() {
+  return (
+    <section className="py-20 px-6 text-center">
+      <div className="max-w-3xl mx-auto">
+        <h1 className="text-6xl font-extrabold tracking-tight text-gray-300">404</h1>
+        <p className="mt-4 text-xl text-gray-500">Page not found</p>
+        <Link href="/" className="mt-8 inline-block text-sm font-medium hover:underline">
+          &larr; Back to home
+        </Link>
+      </div>
+    </section>
+  );
+}

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

@@ -0,0 +1,41 @@
+import { getClient } from "@/lib/client";
+import { PostCard } from "@/components/PostCard";
+
+export default async function Home() {
+  const client = getClient();
+  const settings = await client.getSingleton("site-settings").catch(() => null);
+  const { items: posts } = await client.listContent("posts", {
+    limit: 3,
+    sort: "published_desc",
+  });
+
+  return (
+    <>
+      <section className="py-20 px-6">
+        <div className="max-w-5xl mx-auto text-center">
+          <h1 className="text-5xl font-extrabold tracking-tight">
+            {settings?.body?.siteName || "My Site"}
+          </h1>
+          {settings?.body?.tagline && (
+            <p className="mt-4 text-xl text-gray-500 max-w-2xl mx-auto">
+              {settings.body.tagline as string}
+            </p>
+          )}
+        </div>
+      </section>
+
+      {posts.length > 0 && (
+        <section className="py-12 px-6 bg-gray-50">
+          <div className="max-w-5xl mx-auto">
+            <h2 className="text-2xl font-bold mb-8">Recent Posts</h2>
+            <div className="grid md:grid-cols-3 gap-8">
+              {posts.map((post) => (
+                <PostCard key={post.contentId} title={post.title} snippet={post.snippet} slug={post.slug} />
+              ))}
+            </div>
+          </div>
+        </section>
+      )}
+    </>
+  );
+}

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

@@ -0,0 +1,15 @@
+export function Footer() {
+  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">
+        <p>
+          Powered by{" "}
+          <a href="https://headroom.dev" className="hover:underline">Headroom CMS</a>
+          {" "}&middot;{" "}
+          Built with{" "}
+          <a href="https://nextjs.org" className="hover:underline">Next.js</a>
+        </p>
+      </div>
+    </footer>
+  );
+}

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

@@ -0,0 +1,22 @@
+import Link from "next/link";
+import { getClient } from "@/lib/client";
+
+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";
+
+  return (
+    <header className="border-b border-gray-100 bg-white sticky top-0 z-50">
+      <nav className="max-w-5xl mx-auto px-6 py-4 flex items-center justify-between">
+        <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>
+      </nav>
+    </header>
+  );
+}

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

@@ -0,0 +1,18 @@
+import Link from "next/link";
+
+interface PostCardProps {
+  title: string;
+  snippet?: string;
+  slug: string;
+}
+
+export function PostCard({ title, snippet, slug }: PostCardProps) {
+  return (
+    <Link href={`/blog/${slug}`} className="block group">
+      <article className="bg-white rounded-lg border border-gray-100 p-6 transition-shadow hover:shadow-md">
+        <h3 className="text-lg font-semibold group-hover:text-indigo-700 transition-colors">{title}</h3>
+        {snippet && <p className="mt-2 text-sm text-gray-500 line-clamp-2">{snippet}</p>}
+      </article>
+    </Link>
+  );
+}

package/templates/nextjs/src/lib/client.ts

@@ -0,0 +1,15 @@
+import { HeadroomClient } from "@headroom-cms/api";
+
+let _client: HeadroomClient | null = null;
+
+export function getClient(): HeadroomClient {
+  if (!_client) {
+    _client = new HeadroomClient({
+      url: process.env.HEADROOM_URL || "http://localhost:3000",
+      site: process.env.HEADROOM_SITE || "my.local",
+      apiKey: process.env.HEADROOM_API_KEY || "",
+      imageSigningSecret: process.env.HEADROOM_IMAGE_SIGNING_SECRET || undefined,
+    });
+  }
+  return _client;
+}

package/templates/nextjs/src/lib/links.ts

@@ -0,0 +1,11 @@
+import type { PublicContentRef } from "@headroom-cms/api";
+
+/** Map a content reference to its URL path. */
+export function resolveContentLink(ref: PublicContentRef): string {
+  switch (ref.collection) {
+    case "posts":
+      return `/blog/${ref.slug}`;
+    default:
+      return `/${ref.slug}`;
+  }
+}

package/templates/nextjs/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}