# ai.webhouse.app — AI Builder Site You are an AI coding assistant. A developer has directed you to this URL because they want to build a website using **@webhouse/cms** — a framework-agnostic, file-based, AI-native CMS. This document is self-contained. Follow it **top to bottom**. Every step tells you exactly what to do next and where to fetch more detail if you need it. You do not need to visit any other page to finish a basic build. All URLs below that start with `/ai/` resolve relative to `https://ai.webhouse.app`. --- ## Step 0 — Verify your environment Before anything, confirm: ```bash node --version # must be >= 20 npm --version # or pnpm --version ``` If either is missing: ask the user to install Node.js 20+ from https://nodejs.org and stop. Check which directory you're in. If the user has a project root open in the editor, scaffold inside an empty subdirectory. If not, ask the user for a project name. --- ## Step 1 — Scaffold the project Run in a shell: ```bash npm create @webhouse/cms@latest ``` The interactive wizard asks: 1. **Project name** — becomes the directory name 2. **Template**: - `static-boilerplate` — **default, pick this unless the user specifies otherwise.** Pure static HTML build, no framework runtime, fastest deploy target, zero JS unless you add it - `nextjs-boilerplate` — React + Next.js 16+ (App Router, Server Components). Pick when the user needs ISR, server-rendered auth, or a React ecosystem (next/image, next/font, etc.) - `nextjs-github-boilerplate` — same as `nextjs-boilerplate` but content lives in a GitHub repo (filesystem adapter reads from a cloned repo). Pick for multi-editor workflows with PR-based content review - `preact-boilerplate` — Bun + Vite + Preact 10 + preact-iso + Tailwind v4. Small bundle (~25 kB gzipped), static prerender per route, shadcn-style hand-rolled components, inline SVG icons. Pick for SPA-like interactivity without the React bundle cost 3. **Install dependencies** — yes When it finishes, the directory contains: ``` cms.config.ts # CMS configuration (the file you edit most) content/ # Flat JSON documents, one file per record package.json # Scripts: dev, build, preview CLAUDE.md # Project-specific AI guide (read this once) src/ or app/ # Framework source code ``` Start the dev server: ```bash cd npm run dev ``` Two things happen: - **CMS admin** at http://localhost:3010 (login with the credentials the wizard printed) - **Site** at whichever port the framework uses (Next.js usually 3000, static usually 3009) --- ## Step 2 — Understand the model @webhouse/cms stores content as **JSON files**. Every document is one file at `content/{collection}/{slug}.json`: ```json { "slug": "my-post", "status": "published", "data": { "title": "My Post", "body": "..." }, "id": "unique-id", "_fieldMeta": {} } ``` Rules that **cannot** be violated: - `slug` MUST match the filename without `.json` - `status` MUST be `"draft"`, `"published"`, or `"trashed"` — only `"published"` renders - `_fieldMeta` MUST exist, even if empty `{}` - `data` holds the actual fields as defined in `cms.config.ts` Collections and their fields are declared in `cms.config.ts`: ```typescript import { defineConfig, defineCollection } from '@webhouse/cms'; export default defineConfig({ storage: { adapter: 'filesystem', filesystem: { contentDir: 'content' } }, collections: [ defineCollection({ name: 'posts', label: 'Blog Posts', kind: 'page', // REQUIRED description: 'Long-form articles. Each has its own URL at /blog/{slug}.', // REQUIRED urlPrefix: '/blog', fields: [ { name: 'title', type: 'text', required: true }, { name: 'excerpt', type: 'textarea' }, { name: 'content', type: 'richtext' }, { name: 'date', type: 'date' }, ], }), ], }); ``` **Available field types** (21 total): `text` `textarea` `richtext` `number` `boolean` `date` `image` `image-gallery` `video` `audio` `htmldoc` `file` `interactive` `column-slots` `map` `select` `tags` `relation` `array` `object` `blocks` Full field type reference: fetch `/ai/03-field-types` Full config reference: fetch `/ai/02-config-reference` Real-world multi-collection example: fetch `/ai/10-config-example` --- ## Step 3 — Plan the site with the user Before writing code, ask the user these five questions: 1. **Type of site?** — blog, portfolio, docs, landing page, e-commerce, company site 2. **Content?** — which entity types need to be editable? (pages, posts, products, team, FAQ, testimonials) 3. **Languages?** — one → skip i18n. Multiple → fetch `/ai/17-i18n` 4. **Deploy target?** — Vercel, Netlify, GitHub Pages, Fly.io, Cloudflare Pages (fetch `/ai/18-deployment`) 5. **SEO priority?** — yes for blogs/marketing (fetch `/ai/15-seo`) From the answers, propose a **collection map** before editing `cms.config.ts`. Example output: > I'll create these collections: > - `pages` (kind: page) — static pages like /about, /contact > - `posts` (kind: page) — blog posts at /blog/{slug} > - `team` (kind: data) — team members rendered on /about > - `settings` (kind: global) — site-wide config Wait for confirmation before touching code. --- ## Step 4 — Edit cms.config.ts For **every** collection, pick the right `kind` and write a one-sentence `description`: | Kind | When | AI behavior | |------|------|-------------| | `page` | Has its own URL (blog posts, landing pages) | Full SEO, View pill, sitemap | | `snippet` | Reusable fragment embedded via `{{snippet:slug}}` | No SEO, no URL | | `data` | Rendered on OTHER pages in loops (team, FAQ, testimonials) | No SEO, no View pill | | `form` | Form submissions — read-only from AI | Cannot create documents | | `global` | Single-record site-wide settings | Treated as config | **`description`** answers three questions: 1. What is this? 2. Where does it appear? 3. What references it? Good: ```typescript defineCollection({ name: 'team', kind: 'data', description: 'Team members. Rendered on /about and as bylines on posts via posts.author relation.', fields: [ /* ... */ ], }); ``` Bad (do not do this): ```typescript defineCollection({ name: 'team', fields: [ /* ... */ ] }) // missing kind + description ``` **Reserved collection names** (will break the admin): `site-settings` `settings` `config` `admin` `media` `interactives` Use `globals` for site-wide settings instead. --- ## Step 5 — Create starter content For each collection, create 1-3 sample documents. For example, `content/posts/hello-world.json`: ```json { "slug": "hello-world", "status": "published", "data": { "title": "Hello World", "excerpt": "First post.", "content": "Welcome to the blog.", "date": "2026-04-16" }, "id": "post-1", "_fieldMeta": {} } ``` Checklist per document: - [ ] filename matches `data.slug` - [ ] `status: "published"` - [ ] `_fieldMeta: {}` present - [ ] every `required: true` field has a value - [ ] `image-gallery` values are `{ url, alt }[]` — NEVER plain string arrays --- ## Step 6 — Wire up rendering Depending on the framework picked in Step 1: - **Next.js** → fetch `/ai/08-nextjs-patterns` + `/ai/07-content-structure` - **Static HTML** → see below - **Laravel / Django / Rails / .NET / Go / Java / PHP** → fetch `/ai/21-framework-consumers` and re-export `webhouse-schema.json` with `npx cms export-schema` ### Static build essentials Use env vars `BASE_PATH` (for internal links) and `BUILD_OUT_DIR` (output directory): ```typescript const BASE = (process.env.BASE_PATH ?? '').replace(/\/+$/, ''); const DIST = join(__dirname, process.env.BUILD_OUT_DIR ?? 'dist'); ``` Always filter: ```typescript docs.filter(d => d.status === 'published') ``` NEVER use CDN scripts in static builds (Tailwind CDN, Bootstrap CDN, etc.). Use inline CSS only. For multilingual static sites with `/da/`, `/en/` prefixes: the CMS constructs preview URLs as `urlPrefix + "/" + slug`. Your build must emit redirect HTML files at those slug paths that redirect to the actual locale URL. Without this, preview gives 404. --- ## Step 7 — SEO (if relevant) Every page should have: - `