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 features are activated via License Keys.

Related MCP server: WritBase

🆚 The NextBlock™ Advantage

🏁 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:

npm run dev   # then open http://localhost:4200/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 application

• apps/create-nextblock: scaffolding CLI and template sync pipeline

• libs/db: Supabase clients, package activation checks, migrations, and db types

• libs/editor: reusable Tiptap editor package

• libs/ecommerce: premium commerce package and CMS commerce screens

• libs/sdk: typed block extensibility contract

• libs/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:

1. 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).

2. Cloudflare R2 bucket (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.

3. SMTP credentials (SMTP2GO works very well) — required so Supabase can email the confirmation link your first admin needs to sign in.

Then run:

git clone https://github.com/nextblock-cms/nextblock.git
cd nextblock
npm install
npm run setup
npx nx serve nextblock

npm run setup is informational only — it prompts for nothing and writes no files. Open http://localhost:4200/setup and the browser wizard connects Supabase, applies the schema, configures storage / email, and creates your first administrator.

First login: the dev server runs at http://localhost:4200. Open /sign-up and create your account — the first account to register automatically becomes the ADMIN. Click the confirmation email (or confirm the user in Supabase → Authentication → Users), then sign in to reach 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 anything

• npx nx serve nextblock - Start the local development server for the CMS

• npm run lint - Lint the monorepo

• npm run db:types - Generate Supabase types

• npm run db:migrate:check - Preview pending Supabase migrations safely

• npm run db:migrate / npm run db:push - Apply pending migration files only, without resets or sandbox seeding

• npm run db:migrate:repair-history:check - Preview baseline migration-history repair for existing live databases

• npm run generate:sandbox - Generate sandbox data

• npm 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.

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.

• X (Twitter): @NextBlockCMS

• LinkedIn: NextBlock™

• GitHub: nextblock-cms/nextblock

• Medium: @nextblockcms

• Dev.to: nextblockcms

🙏 Acknowledgements

Thanks to Vercel for their support of open-source software.