create-headroom-site 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-headroom-site",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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

@@ -51,6 +51,80 @@ npm run preview           # Preview built site
 npm run generate:schemas  # Generate Zod schemas from Headroom collections
 ```
 
+## Headroom CLI
+
+The `@headroom-cms/cli` package is included as a dev dependency and provides a full admin CLI for managing your Headroom CMS. Run it via `npx headroom` or add scripts to `package.json`.
+
+### Setup
+
+```bash
+# Login to your Headroom instance
+npx headroom login https://your-headroom-url.cloudfront.net your-site.com \
+  --email admin@example.com --password-stdin
+
+# Verify login
+npx headroom whoami
+
+# Set the active site (if managing multiple sites)
+npx headroom site your-site.com
+```
+
+### Key Commands
+
+```bash
+# Collections
+npx headroom collections list --table          # List all collections
+npx headroom collections describe posts        # Show field schema with constraints
+npx headroom collections example posts         # Generate JSON template for content creation
+
+# Content
+npx headroom content list --table                           # List all content
+npx headroom content list --collection posts --table        # List by collection
+npx headroom content list --related-to "author:01ABC" --table  # Filter by relationship
+npx headroom content get <content-id>                       # Get single item with body
+npx headroom content references <content-id> --table        # What references this content?
+npx headroom content create --collection posts --data '{"title":"New Post"}'
+npx headroom content publish <content-id>
+npx headroom content delete <content-id> --force
+
+# Media
+npx headroom media list --table                # List media files
+npx headroom media upload ./image.jpg          # Upload a local file
+npx headroom media upload-url https://...      # Upload from URL
+
+# API Keys
+npx headroom api-keys list --table
+npx headroom api-keys create --data '{"label":"My Key"}'
+
+# Tags
+npx headroom tags list --table
+
+# Audit log
+npx headroom audit list --table
+```
+
+### Output Formats
+
+```bash
+npx headroom content list --table          # Human-readable table
+npx headroom content list                  # JSON (pipe to jq)
+npx headroom content list --quiet          # Exit code only
+npx headroom content list --debug          # Show HTTP request/response details
+```
+
+### Using with CI/CD
+
+```bash
+# Non-interactive login
+echo "$HEADROOM_PASSWORD" | npx headroom login "$HEADROOM_URL" "$HEADROOM_SITE" \
+  --email "$HEADROOM_EMAIL" --password-stdin
+
+# Publish all draft content in a collection
+npx headroom content list --collection posts --status draft | \
+  jq -r '.items[].contentId' | \
+  xargs -I{} npx headroom content publish {}
+```
+
 ## Default Collections
 
 New Headroom sites are scaffolded with three collections:

package/templates/astro/package.json

@@ -10,9 +10,10 @@
   },
   "dependencies": {
     "astro": "^5.0.0",
-    "@headroom-cms/api": "^0.1.4"
+    "@headroom-cms/api": "^0.1.6"
   },
   "devDependencies": {
+    "@headroom-cms/cli": "^0.1.5",
     "@tailwindcss/vite": "^4.0.0",
     "tailwindcss": "^4.0.0",
     "tsx": "^4.0.0",

package/templates/nextjs/CLAUDE.md

@@ -21,9 +21,10 @@ src/
 │   │   ├── page.tsx         # Blog listing
 │   │   └── [slug]/page.tsx  # Blog post detail
 │   └── [slug]/page.tsx      # Dynamic pages from "pages" collection
-├── components/              # Reusable React components
+├── components/              # Reusable React components (pure presentation, receive data via props)
 └── lib/
     ├── client.ts            # Singleton HeadroomClient instance
+    ├── settings.ts          # React.cache() wrapper for site-settings (deduplicates per request)
     └── links.ts             # Content link resolver (maps refs to URL paths)
 ```
 
@@ -47,6 +48,80 @@ npm run start             # Start production server
 npm run generate:schemas  # Generate Zod schemas from Headroom collections
 ```
 
+## Headroom CLI
+
+The `@headroom-cms/cli` package is included as a dev dependency and provides a full admin CLI for managing your Headroom CMS. Run it via `npx headroom` or add scripts to `package.json`.
+
+### Setup
+
+```bash
+# Login to your Headroom instance
+npx headroom login https://your-headroom-url.cloudfront.net your-site.com \
+  --email admin@example.com --password-stdin
+
+# Verify login
+npx headroom whoami
+
+# Set the active site (if managing multiple sites)
+npx headroom site your-site.com
+```
+
+### Key Commands
+
+```bash
+# Collections
+npx headroom collections list --table          # List all collections
+npx headroom collections describe posts        # Show field schema with constraints
+npx headroom collections example posts         # Generate JSON template for content creation
+
+# Content
+npx headroom content list --table                           # List all content
+npx headroom content list --collection posts --table        # List by collection
+npx headroom content list --related-to "author:01ABC" --table  # Filter by relationship
+npx headroom content get <content-id>                       # Get single item with body
+npx headroom content references <content-id> --table        # What references this content?
+npx headroom content create --collection posts --data '{"title":"New Post"}'
+npx headroom content publish <content-id>
+npx headroom content delete <content-id> --force
+
+# Media
+npx headroom media list --table                # List media files
+npx headroom media upload ./image.jpg          # Upload a local file
+npx headroom media upload-url https://...      # Upload from URL
+
+# API Keys
+npx headroom api-keys list --table
+npx headroom api-keys create --data '{"label":"My Key"}'
+
+# Tags
+npx headroom tags list --table
+
+# Audit log
+npx headroom audit list --table
+```
+
+### Output Formats
+
+```bash
+npx headroom content list --table          # Human-readable table
+npx headroom content list                  # JSON (pipe to jq)
+npx headroom content list --quiet          # Exit code only
+npx headroom content list --debug          # Show HTTP request/response details
+```
+
+### Using with CI/CD
+
+```bash
+# Non-interactive login
+echo "$HEADROOM_PASSWORD" | npx headroom login "$HEADROOM_URL" "$HEADROOM_SITE" \
+  --email "$HEADROOM_EMAIL" --password-stdin
+
+# Publish all draft content in a collection
+npx headroom content list --collection posts --status draft | \
+  jq -r '.items[].contentId' | \
+  xargs -I{} npx headroom content publish {}
+```
+
 ## Default Collections
 
 New Headroom sites are scaffolded with three collections:
@@ -59,7 +134,15 @@ New Headroom sites are scaffolded with three collections:
 
 ## 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).
+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). The layout uses `force-dynamic` to ensure fresh data on every request.
+
+### Dev Auto-Refresh
+
+In development (`NODE_ENV === "development"`), the layout includes a `DevRefresh` component from `@headroom-cms/api/next` that polls the CMS `/version` endpoint and calls `router.refresh()` when content changes, so edits in the admin UI are reflected without manual reload.
+
+### Site Settings
+
+Site settings are fetched via `getSettings()` from `src/lib/settings.ts`, which uses `React.cache()` to deduplicate the fetch across layout and page components within the same request. The layout fetches settings once and passes them as props to `Header` and `Footer` (pure presentation components).
 
 ### Getting the Client
 

package/templates/nextjs/package.json

@@ -12,9 +12,10 @@
     "next": "^15.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@headroom-cms/api": "^0.1.4"
+    "@headroom-cms/api": "^0.1.6"
   },
   "devDependencies": {
+    "@headroom-cms/cli": "^0.1.5",
     "@tailwindcss/postcss": "^4.0.0",
     "tailwindcss": "^4.0.0",
     "tsx": "^4.0.0",

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

@@ -1,18 +1,10 @@
 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 { getSettings } from "@/lib/settings";
 import "./globals.css";
 
-const getSettings = unstable_cache(
-  async () => {
-    const client = getClient();
-    return client.getSingleton("site-settings");
-  },
-  ["site-settings"],
-  { revalidate: 3600 }
-);
+export const dynamic = "force-dynamic";
 
 export async function generateMetadata(): Promise<Metadata> {
   try {
@@ -28,14 +20,32 @@ export async function generateMetadata(): Promise<Metadata> {
   }
 }
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const settings = await getSettings().catch(() => null);
+  const siteName = (settings?.body?.siteName as string) || "My Site";
+  const menuItems = (settings?.body?.menuItems as Array<{ label: string; href: string }>) || [];
+  const footerText = (settings?.body?.footerText as string) || "";
+
   return (
     <html lang="en">
       <body className="min-h-screen flex flex-col">
-        <Header />
+        {process.env.NODE_ENV === "development" && <DevRefreshLoader />}
+        <Header siteName={siteName} menuItems={menuItems} />
         <main className="flex-1">{children}</main>
-        <Footer />
+        <Footer footerText={footerText} />
       </body>
     </html>
   );
 }
+
+async function DevRefreshLoader() {
+  const { DevRefresh } = await import("@headroom-cms/api/next");
+  const url = process.env.HEADROOM_URL || "http://localhost:3000";
+  const site = process.env.HEADROOM_SITE || "my.local";
+  return (
+    <DevRefresh
+      versionUrl={`${url}/v1/${site}/version`}
+      apiKey={process.env.HEADROOM_API_KEY || ""}
+    />
+  );
+}

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

@@ -1,4 +1,5 @@
 import { getClient } from "@/lib/client";
+import { getSettings } from "@/lib/settings";
 import { PostCard } from "@/components/PostCard";
 import { BlockRenderer } from "@headroom-cms/api/react";
 import "@headroom-cms/api/react/headroom-blocks.css";
@@ -7,12 +8,11 @@ import type { Block, RefsMap } from "@headroom-cms/api";
 
 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",
-  });
-  const homePage = await client.getContentBySlug("pages", "home").catch(() => null);
+  const [settings, { items: posts }, homePage] = await Promise.all([
+    getSettings().catch(() => null),
+    client.listContent("posts", { limit: 3, sort: "published_desc" }),
+    client.getContentBySlug("pages", "home").catch(() => null),
+  ]);
   const homeBlocks = (homePage?.body?.content || []) as Block[];
   const homeRefs = (homePage?._refs || {}) as RefsMap;
 

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

@@ -1,10 +1,8 @@
-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) || "";
+interface FooterProps {
+  footerText: string;
+}
 
+export function Footer({ footerText }: FooterProps) {
   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">

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

@@ -1,12 +1,11 @@
 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";
-  const menuItems = (settings?.body?.menuItems as Array<{ label: string; href: string }>) || [];
+interface HeaderProps {
+  siteName: string;
+  menuItems: Array<{ label: string; href: string }>;
+}
 
+export function Header({ siteName, menuItems }: HeaderProps) {
   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">

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

@@ -0,0 +1,8 @@
+import { cache } from "react";
+import { getClient } from "./client";
+
+/** Per-request cached site settings fetch. Deduplicates across layout + pages in a single render. */
+export const getSettings = cache(async () => {
+  const client = getClient();
+  return client.getSingleton("site-settings");
+});