Define your content schema once. Manage it visually. Let AI help write it. Render it from any framework. Deploy anywhere.
Your content lives as flat JSON files in your git repo — readable by Next.js, Laravel, Django, Spring Boot, .NET, Rails, Hugo, or any other language. The CMS admin is a Next.js app, but the content layer is universal. See examples/consumers/ for working Java and .NET reference apps.
npm create @webhouse/cms my-site
cd my-site
bash start.sh
That's it. Claude Code or other AI platforms reads your schema, builds a Next.js site or through other frameworks, and you manage content through the admin UI.
What is this?
@webhouse/cms is a file-based, code-first content management system. You define collections and fields in cms.config.ts, and the CMS stores content as flat JSON files in a content/ directory. No database required. Git-committable. AI-native from day one.
// cms.config.ts
import { defineConfig, defineCollection } from '@webhouse/cms';
export default defineConfig({
collections: [
defineCollection({
name: 'posts',
label: 'Blog Posts',
fields: [
{ name: 'title', type: 'text', required: true },
{ name: 'excerpt', type: 'textarea' },
{ name: 'content', type: 'richtext' },
{ name: 'date', type: 'date' },
{ name: 'author', type: 'relation', collection: 'team' },
{ name: 'tags', type: 'tags' },
{ name: 'featured', type: 'boolean' },
],
}),
],
});
Content is stored as JSON — read it directly in Next.js, Astro, or any framework:
// Read content — no SDK, no API, just files
import { readFileSync } from 'node:fs';
const post = JSON.parse(readFileSync('content/posts/hello-world.json', 'utf-8'));
console.log(post.data.title); // "Hello, World!"
Admin UI — 5 ways to run it
The visual admin interface for managing content. Open source, full-featured, works with any site.
1. Hosted cloud (coming soon)
https://webhouse.app
Sign in, connect your GitHub repo, manage content from anywhere. Zero setup.
2. npx — one command, local install
npx @webhouse/cms-admin-cli
Auto-detects cms.config.ts in your project. First run builds and caches the admin (~2 min). Subsequent starts are instant.
npx @webhouse/cms-admin-cli --config ./cms.config.ts # explicit config
npx @webhouse/cms-admin-cli -p 4000 # custom port
npx @webhouse/cms-admin-cli --update # force rebuild
3. Docker — isolated, reproducible
docker run -p 3010:3010 -v $(pwd):/site ghcr.io/webhousecode/cms-admin:latest
Published to GHCR for linux/amd64 + linux/arm64. Mounts your project at /site, auto-detects cms.config.ts, serves admin on port 3010.
- Stable:
:latestor:0.3.0— tagged releases - Weekly:
:weekly— automated Monday builds
4. Tarball — Node.js only, no Docker
curl -L https://github.com/webhousecode/cms/releases/latest/download/cms-admin.tar.gz | tar xz
cd cms-admin-*
./run.sh
Requires Node.js 22+. Runs on Linux, macOS, and Windows (WSL/Git Bash). First boot prompts for admin email + password via the setup wizard. See docs.webhouse.app/docs/releases for all download channels, or the plain-text releases.txt feed for scripts.
5. Git clone — full source access
git clone https://github.com/webhousecode/cms.git
cd cms
pnpm install
pnpm dev
Admin runs on localhost:3010. Set CMS_CONFIG_PATH to point at your site's config.
Features
Content engine
- 16 field types — text, textarea, richtext, number, boolean, date, image, video, select, tags, relation, array, object, blocks, image-gallery
- Block editor — composable page sections with nested fields
- Relations — cross-collection references (single and multi)
- Structured arrays — arrays of objects with per-item field editors
- Nested objects — deeply nested field structures with JSON/UI toggle
- i18n — multi-locale content with AI-powered translation
- Scheduled publishing — set a future date, auto-publishes
Admin UI
- Visual document editor — every field type has a dedicated editor
- Block editor — drag-and-drop sections with type picker
- Multi-site management — manage multiple sites from one admin
- GitHub integration — OAuth login, create repos, manage GitHub-backed content
- Site switcher — fast switching between projects
- Rich text editor — Markdown with live preview
- Media library — upload, browse, and manage images
- Revision history — view diffs and restore previous versions
- AI assistant — generate, rewrite, and optimize content from the editor
AI-native
- Content generation —
cms ai generate posts "Write about TypeScript generics" - Rewriting —
cms ai rewrite posts/hello "Make it more concise" - SEO optimization —
cms ai seoacross all published content - AI Lock — field-level protection prevents AI from overwriting human edits
- Brand voice — configurable tone, audience, and style guidelines
- MCP support — expose content to AI assistants via Model Context Protocol
Developer experience
- TypeScript-first — schemas defined in code, fully typed
- File-based — JSON files in
content/, git-committable - No database — filesystem adapter by default, SQLite and GitHub also available
- CLI tools — init, dev, build, serve, AI commands
- Claude Code ready — CLAUDE.md included in npm package,
.mcp.jsonpre-configured
Storage adapters
// Filesystem (default)
storage: { adapter: 'filesystem', filesystem: { contentDir: 'content' } }
// GitHub
storage: { adapter: 'github', github: { owner: 'myorg', repo: 'my-site', token: process.env.GITHUB_TOKEN } }
// SQLite
storage: { adapter: 'sqlite', sqlite: { path: './data/cms.db' } }
Packages
CLI
Install globally for the short cms command:
npm install -g @webhouse/cms-cli
Note: Do not use
npx cms— npm resolves it to an unrelated package. Usenpx @webhouse/cms-cliif you prefer not to install globally.
Commands
AI commands
Require ANTHROPIC_API_KEY or OPENAI_API_KEY in .env.
# Examples
cms ai generate posts "Write a guide to TypeScript generics"
cms ai rewrite posts/hello-world "Make it more concise and add code examples"
cms ai seo
MCP commands
Content creation — 3 ways
A) Via AI generation
cms ai generate posts "Write a blog post about TypeScript best practices"
B) Via REST API
curl -X POST http://localhost:3000/api/content/posts \
-H "Content-Type: application/json" \
-d '{"slug":"my-post","status":"published","data":{"title":"My Post","content":"# Hello"}}'
C) Via Claude Code
> Create a blog post about why file-based CMS is the future
REST API
The dev server (cms dev) exposes a full REST API. See the complete OpenAPI specification.
Endpoints
Example
# List all published posts
curl http://localhost:3000/api/content/posts?status=published
# Get a single post
curl http://localhost:3000/api/content/posts/hello-world
# Create a post
curl -X POST http://localhost:3000/api/content/posts \
-H "Content-Type: application/json" \
-d '{
"slug": "my-post",
"status": "draft",
"data": {
"title": "My First Post",
"content": "# Hello\n\nThis is my first post.",
"date": "2026-03-15"
}
}'
Building a site with Claude Code
Every scaffolded project includes a CLAUDE.md that teaches AI how to use the CMS. The @webhouse/cms npm package also ships with a comprehensive CLAUDE.md.
# Scaffold and let AI build your site
npm create @webhouse/cms my-site
cd my-site
claude "Build a portfolio site with Next.js and Tailwind. Read CLAUDE.md for CMS docs."
Or use the included start script:
bash start.sh "Build a dark-themed blog with categories and author pages"
Claude Code will:
- Read
CLAUDE.mdand understand the CMS - Create a Next.js App Router site
- Define collections in
cms.config.ts - Create content in
content/as JSON files - Build pages that read content from the filesystem
- Suggest running the admin UI when done
Architecture
┌─────────────────────────────────────────────────────────────┐
│ webhouse.app / cms-admin (Visual Admin UI) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Document │ │ Block │ │ Media │ │ AI Cockpit │ │
│ │ Editor │ │ Editor │ │ Library │ │ & Agents │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ @webhouse/cms (Core Engine) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Schema │ │ Content │ │ Storage │ │ API │ │
│ │ Validate │ │ Service │ │ Adapters │ │ (Hono) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Storage │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │Filesystem│ │ GitHub │ │ SQLite │ │
│ │ (JSON) │ │ API │ │ (Drizzle)│ │
│ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────────────────────┤
│ AI Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Generate │ │ Rewrite │ │Translate │ │ SEO Agent │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
│ ┌──────────┐ ┌──────────┐ │
│ │ MCP Read │ │MCP Write │ (Model Context Protocol) │
│ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
Development
git clone https://github.com/webhousecode/cms.git
cd cms
pnpm install
pnpm build # Build all packages
pnpm dev # Start admin on :3010
Project structure
packages/
cms/ # Core engine
cms-admin/ # Next.js admin UI
cms-admin-cli/ # npx wrapper for admin
cms-ai/ # AI agents
cms-cli/ # CLI tools
cms-mcp-client/ # Public MCP server
cms-mcp-server/ # Admin MCP server
create-cms/ # Project scaffolder
examples/
blog/ # Blog example
landing/ # Landing page with blocks
deploy/
Dockerfile.cms # Combined site + admin image
Dockerfile.admin # Standalone admin image
fly.toml # Fly.io deployment config
