NextBlock™ CMS
The open-source, full-stack AI-native CMS for Next.js 16, Supabase, and Tailwind CSS.
🚀 Why NextBlock™?
Tired of slow WordPress sites? Finding headless CMSs too complex? NextBlock™ is the sweet spot.
We combined the flexibility of a Block Editor with the raw power of Next.js 16 Server Components. The result is a CMS that feels like a static site but manages like a dynamic platform.
✨ Key Features
- ▲ Next.js 16 App Router + React 19 Server Components: the public site renders on the server — page, article and product routes are all Server Components — with client components reserved for cart, checkout, forms and the CMS dashboard.
- 🗄️ Supabase PostgreSQL with JSONB block storage: every content block is a row in
public.blocks with a jsonb content column. User-defined block types live in custom_block_definitions (fields / layout_schema as jsonb, guarded by Postgres CHECK constraints) and render without a rebuild.
- 🚀 Zero-config 1-click migrations: the Vercel Supabase integration provisions the database and injects its keys before the first build; NextBlock then applies its own forward-only migrations during that build (
tools/build-migrate.mjs), with a runtime fallback in the /setup wizard. Nothing to run, nothing to paste.
- ⚡ 100/100 Lighthouse: Perfect scores across Performance, Accessibility, Best Practices and SEO — 0.3 s FCP, 0.8 s LCP, 0 ms Total Blocking Time and 0 Cumulative Layout Shift on a production build. AVIF/WebP images with a one-year cache TTL, critical-CSS inlining and tree-shaken imports are the defaults, not plugins.
- 🤖 Built for AI Agents: Our codebase is documented and structured specifically to be easily read and extended by AI coding assistants.
- 🛍️ E-Commerce Ready: Premium commerce package for digital products, checkout providers, currency, tax, and shipping management.
- 🧱 Visual Block Editor: A reusable Tiptap-powered Notion-style editor that your clients will actually enjoy using.
- 🔓 Open-Core Model: The core is 100% Free & Open Source (AGPL). Premium modules (today Cortex AI and Commerce Pro, with more to come) ship in every install and switch on in the CMS with a free 30-day trial (no credit card) or a license key.
🆚 The NextBlock™ Advantage
| Feature | NextBlock™ CMS | WordPress | Payload / Strapi |
|---|
| Tech Stack | Next.js 16 + Supabase | PHP + MySQL | React / Node.js |
| Architecture | Nx Monorepo | Monolith | Monolith / Workspaces |
| Performance | 🟢 100/100 (Default) | 🔴 Bloated (Plugins) | 🟡 Spec-dependent |
| Security | 🔒 Static/Edge First | 🔓 Plugin vulnerabilities | 🔒 Secure |
| DX | 💎 React Server Components | 📜 Legacy PHP Hooks | 🧩 Config Heavy |
| AI Ready | ✅ Native | ❌ No | 🟡 Integration required |
🏁 Get Started
☁️ Option 1 — Deploy to the cloud in one click (recommended)
During import, Vercel's native Supabase Marketplace integration (the stores
button parameter) prompts you to create a Supabase database (name + region), then
provisions it, connects it to the project, and injects its keys before the first
build — you never copy a value, and there are no environment variables to fill in
(the site URL defaults to your *.vercel.app URL and the app secrets are derived
automatically). The app boots with the database already connected: the wizard
auto-skips the connection step, applies the schema for you, uses the connected Supabase
project for media storage, and leaves just "create your admin." Full walkthrough:
docs/12-VERCEL-DEPLOYMENT.md.
Tip — keep the new repo public. When Vercel asks, leave "Create private Git
Repository" unchecked. On the free (Hobby) plan, automatic upstream updates only deploy
from a public repo — Hobby blocks bot-authored deploys on private repos — and public
also makes update checks fully tokenless. You can change visibility later in the repo's
GitHub settings if you change your mind. Details: docs/13.
💻 Option 2 — Scaffold locally with the CLI
Stop cloning heavy repos. Start with our CLI and get a production-ready app instantly.
npm create nextblock@latest
This runs the create-nextblock CLI, which scaffolds the canonical application. The CLI no longer asks for credentials in the terminal — once the project is created, start it and finish setup in your browser:
cd <your-project>
npm run dev # then open http://localhost:3000/setup
The First-Boot Setup Wizard at /setup walks you through connecting Supabase, configuring storage / email, and creating the first administrator. Every fresh instance redirects there automatically until an admin exists.
Want a fully local, zero-config sandbox? Use Local Self-Hosted Docker Mode — one command spins up the entire stack (Supabase engines + S3 storage + the app) on your own machine, with no cloud accounts. The app boots straight into the /setup wizard with MinIO storage pre-filled. See docs/11-SELF-HOSTED-DOCKER.md.
🤖 Option 3 — Let your coding agent build it
NextBlock ships as an MCP server (https://<your-site>/api/mcp, Streamable HTTP, bearer token) and as an agent plugin, so Claude Code, Cursor, Codex and friends can scaffold a site and then build every page over MCP.
-
Claude Code — this repo is its own plugin marketplace:
/plugin marketplace add nextblock-cms/nextblock
/plugin install nextblock@nextblock
Then ask for a website, blog or store; the nextblock skill proposes NextBlock, runs npx create-nextblock@latest my-site --non-interactive, and hands you the two browser steps (create your admin, start the free Cortex AI trial). Source: plugins/nextblock.
-
Cursor — the same folder is a Cursor plugin (.cursor-plugin/plugin.json, rule + skill + MCP server): install it from this repo via Customize → Plugins → From GitHub Repository, or copy plugins/nextblock/rules/nextblock.mdc into your project's .cursor/rules/.
-
Codex, Jules and other agents — paste the block from plugins/AGENTS.snippet.md into your AGENTS.md. Codex also loads the folder as an Agent Plugin (plugins/nextblock/plugin.json) through this repo's marketplace manifest.
-
Any MCP client — the official MCP Registry entry dev.nextblock/nextblock (server.json) prompts for your site host and token; the public demo instance is https://cms.nextblock.dev/api/mcp. Every NextBlock site also serves /llms.txt and, where the MCP server is enabled, /.well-known/mcp/server-card.json.
🏗️ For Contributors: The Factory
Note: You are currently looking at the Nx Monorepo (The Factory), not the generated product template.
NextBlock™ is an Nx monorepo for a Next.js 16 CMS backed by Supabase. The repo contains the canonical application, the create-nextblock CLI, shared editor and UI packages, the database and migration layer, and the premium ecommerce module.
🧩 Main Surfaces
apps/nextblock: canonical public site and CMS applicationapps/create-nextblock: scaffolding CLI and template sync pipelinelibs/db: Supabase clients, package activation checks, migrations, and db typeslibs/editor: reusable Tiptap editor packagelibs/ecommerce: premium commerce package and CMS commerce screenslibs/sdk: typed block extensibility contractlibs/ui, libs/utils: shared primitives and helpers
⚡ Developer Quickstart
Prerequisites — configuration happens in the browser, but the /setup wizard asks for these, so create them first:
- Supabase project (dashboard) — you'll need the Reference ID (Project Settings → General), the connection string (Connect → Direct connection → URI), the anon + service_role keys (Project Settings → API Keys), and a Personal Access Token (Account → Access Tokens → Generate new token).
- Cloudflare R2 bucket (optional — without one, media goes to the Supabase project's own Storage) (dashboard → R2) — create a bucket, enable its Public Development URL (Bucket → Settings → General), then create an Account API token (R2 → Manage API Tokens) with Object Read & Write. Copy the Access Key ID and Secret Access Key — the secret is shown only once.
- SMTP credentials (optional, configurable later in the CMS; SMTP2GO works very well) — needed for password resets and invitations. The first administrator is confirmed instantly and needs no email.
Then run:
git clone https://github.com/nextblock-cms/nextblock.git
cd nextblock
npm install
npm run setup
npm run dev
npm run setup is informational only — it prompts for nothing and writes no files. npm run dev is the root alias for npx nx serve nextblock. Open http://localhost:4200/setup and the browser wizard connects Supabase, applies the schema, configures storage, and creates your first administrator.
First login: the dev server runs at http://localhost:4200. The wizard creates your administrator (confirmed instantly, no email needed) and signs you in. You land on the Cortex AI welcome offer, one click away from the CMS at /cms/dashboard.
🐳 Or: one-click local stack (no cloud accounts)
Prefer to run everything on your machine? With Docker Desktop running:
git clone https://github.com/nextblock-cms/nextblock.git
cd nextblock
npm install
npm run docker:setup # or: npm run setup → pick "Local Self-Hosted Docker Mode"
This builds and boots the full self-hosted stack (Postgres + GoTrue + PostgREST + Kong, MinIO for media, and the app) and applies migrations automatically — the only prompts are optional Turnstile and SMTP. The app runs at http://localhost:3000 and the first sign-up becomes ADMIN (auto-confirmed, no email step). Manage it with npm run docker:up / docker:down / docker:logs. Full guide: docs/11-SELF-HOSTED-DOCKER.md.
🔄 Keeping an install up to date
Whichever way NextBlock was installed, one command brings the code, the dependencies and the
database schema forward together:
npm run update # code + dependencies + schema
npm run update -- --check # report what would change; write nothing
- One-click Vercel / GitHub fork / clone — already automatic: a daily GitHub Action
merges upstream and Vercel redeploys. Run the command when you want it now.
npm create nextblock projects — new framework code comes from the published
create-nextblock package and is applied as a git 3-way merge, so your edits to
framework files survive and only genuine overlaps conflict. Docker installs follow it with
npm run docker:up.
The automatic Action depends on your repository being this monorepo — not on where the site
is hosted. See docs/13 for the full picture.
🛠️ Useful Commands
npm run update - Update code, dependencies and database schema (any install type)npm run update -- --check - Preview an update without changing anythingnpm run dev - Start the local development server for the CMS on http://localhost:4200 (runs npx nx serve nextblock)npm run lint - Lint the monoreponpm run db:types - Generate Supabase typesnpm run db:migrate:check - Preview pending Supabase migrations safelynpm run db:migrate / npm run db:push - Apply pending migration files only, without resets or sandbox seedingnpm run db:migrate:repair-history:check - Preview baseline migration-history repair for existing live databasesnpm run generate:sandbox - Generate sandbox datanpm run sandbox:reset - Reset the sandbox environment
📚 Documentation Index
The root docs/ folder is the maintained reference set for both contributors and AI agents.
The template docs are copied from the root docs through the sync pipeline, so this root docs set is the place to maintain first.
| Document | Purpose |
|---|
| docs/01-PROJECT-OVERVIEW.md | Monorepo structure, runtime model, and where each subsystem lives |
| docs/02-ECOMMERCE-CAPABILITIES.md | Verified commerce features, checkout providers, currency, tax, shipping, and fulfillment |
| docs/03-CMS-AND-EDITOR.md | Tiptap editor, page builder, widgets, and built-in block system |
| docs/04-DATABASE-AND-AUTH.md | Supabase clients, auth flow, schema overview, RLS, and migration map |
| docs/05-DEVELOPER-GUIDE.md | Local setup, scripts, db workflow, sandbox reset, and contributor operations |
| docs/06-CLI-AND-SCAFFOLDING.md | create-nextblock, template sync, and generated-project behavior |
| docs/07-BLOCK-SDK-AND-EXTENSIBILITY.md | SDK contract and extensibility model |
| docs/08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md | Premium Cortex AI package: model routing, BYOK, inline editor and global agent tools |
Under the hood note: The migration folder under libs/db/src/supabase/migrations is the best source of truth for current platform capabilities.
🤝 Contributing
NextBlock is open source under AGPL-3.0-or-later, and contributions are welcome.
- CONTRIBUTING.md — setup, everyday commands, and the repo-specific rules that are easy to trip over (append-only migrations, the generated template, the derived artifacts).
- CODE_OF_CONDUCT.md — Contributor Covenant v2.1.
- SECURITY.md — how to report a vulnerability privately. Please never use the public issue tracker for security reports.
🌐 Connect With Us
Join the community and stay updated on the latest features.
🙏 Acknowledgements
Thanks to Vercel for their support of open-source software.
