# NextBlock™ CMS **The open-source, full-stack AI-native CMS for Next.js 16, Supabase, and Tailwind CSS.**

Deploy a production Next.js 16 + Supabase website and CMS in one click.
Vercel provisions the database and injects its keys before the first build, NextBlock applies its own
schema during that build, and the in-app wizard asks only for your admin account.
No environment variables to fill in.

Live Sandbox · Documentation · Deploy Guide · GitHub

_{Sandbox resets every 15 minutes · User: demo@nextblock.dev · Pass: password}

--- ## 🚀 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](./docs/assets/lighthouse-scores.png)**: 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) [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fnextblock-cms%2Fnextblock&project-name=nextblock&repository-name=nextblock&stores=%5B%7B%22type%22%3A%22integration%22%2C%22integrationSlug%22%3A%22supabase%22%2C%22productSlug%22%3A%22supabase%22%7D%5D&demo-title=NextBlock%20CMS&demo-description=Open-source%20Next.js%2016%20%2B%20Supabase%20CMS%20with%20a%20block%20editor%2C%20SEO%20engine%2C%20bilingual%20content%20and%20an%20MCP%20server%20for%20AI%20agents.&demo-url=https%3A%2F%2Fcms.nextblock.dev%2F&demo-image=https%3A%2F%2Fcms.nextblock.dev%2Fassets%2Fnextblock-banner.jpg) 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](./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](./docs/13-STAYING-UP-TO-DATE.md). ### 💻 Option 2 — Scaffold locally with the CLI Stop cloning heavy repos. Start with our CLI and get a production-ready app instantly. ```bash 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: ```bash cd 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](./docs/11-SELF-HOSTED-DOCKER.md). ### 🤖 Option 3 — Let your coding agent build it NextBlock ships as an MCP server (`https:///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: ```text /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](./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](./plugins/nextblock/rules/nextblock.mdc) into your project's `.cursor/rules/`. - **Codex, Jules and other agents** — paste the block from [plugins/AGENTS.snippet.md](./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](./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](https://supabase.com/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** (optional — without one, media goes to the Supabase project's own Storage) ([dashboard](https://dash.cloudflare.com) → 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** (optional, configurable later in the CMS; [SMTP2GO](https://www.smtp2go.com) works very well) — needed for password resets and invitations. The first administrator is confirmed instantly and needs no email. Then run: ```bash 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: ```bash 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](./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: ```bash 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](./docs/13-STAYING-UP-TO-DATE.md)** 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 - `npm run dev` - Start the local development server for the CMS on http://localhost:4200 (runs `npx nx serve nextblock`) - `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._ | Document | Purpose | | :--------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | | [docs/01-PROJECT-OVERVIEW.md](./docs/01-PROJECT-OVERVIEW.md) | Monorepo structure, runtime model, and where each subsystem lives | | [docs/02-ECOMMERCE-CAPABILITIES.md](./docs/02-ECOMMERCE-CAPABILITIES.md) | Verified commerce features, checkout providers, currency, tax, shipping, and fulfillment | | [docs/03-CMS-AND-EDITOR.md](./docs/03-CMS-AND-EDITOR.md) | Tiptap editor, page builder, widgets, and built-in block system | | [docs/04-DATABASE-AND-AUTH.md](./docs/04-DATABASE-AND-AUTH.md) | Supabase clients, auth flow, schema overview, RLS, and migration map | | [docs/05-DEVELOPER-GUIDE.md](./docs/05-DEVELOPER-GUIDE.md) | Local setup, scripts, db workflow, sandbox reset, and contributor operations | | [docs/06-CLI-AND-SCAFFOLDING.md](./docs/06-CLI-AND-SCAFFOLDING.md) | `create-nextblock`, template sync, and generated-project behavior | | [docs/07-BLOCK-SDK-AND-EXTENSIBILITY.md](./docs/07-BLOCK-SDK-AND-EXTENSIBILITY.md) | SDK contract and extensibility model | | [docs/08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md](./docs/08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md) | Premium Cortex AI package: model routing, BYOK, inline editor and global agent tools | | [docs/09-LIVE-DRAFT-MODE.md](./docs/09-LIVE-DRAFT-MODE.md) | Real-time visual editing and non-destructive draft previewing | | [docs/10-CUSTOM-BLOCKS.md](./docs/10-CUSTOM-BLOCKS.md) | Data-driven custom blocks: schema, CRUD, dynamic rendering, and import/export | | [docs/11-SELF-HOSTED-DOCKER.md](./docs/11-SELF-HOSTED-DOCKER.md) | One-click local self-hosted Docker stack: Supabase engines, MinIO storage, migration runner, and how it maps to cloud | | [docs/12-VERCEL-DEPLOYMENT.md](./docs/12-VERCEL-DEPLOYMENT.md) | One-click cloud deploy, the browser setup wizard, and Supabase env-var aliases | | [docs/13-STAYING-UP-TO-DATE.md](./docs/13-STAYING-UP-TO-DATE.md) | `npm run update` for all four installs, the daily upstream-sync Action, and how migrations reach a deployed site | | [docs/README.md](./docs/README.md) | Audience-based docs index | > **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](./LICENSE.md), and contributions are welcome. - **[CONTRIBUTING.md](./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](./CODE_OF_CONDUCT.md)** — Contributor Covenant v2.1. - **[SECURITY.md](./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](https://x.com/NextBlockCMS) - **LinkedIn:** [NextBlock™](https://www.linkedin.com/in/nextblock/) - **GitHub:** [nextblock-cms/nextblock](https://github.com/nextblock-cms/nextblock) - **Medium:** [@nextblockcms](https://medium.com/@nextblockcms) - **Dev.to:** [nextblockcms](https://dev.to/nextblockcms) --- ## 🙏 Acknowledgements Thanks to [Vercel](https://vercel.com) for their support of open-source software. ---

_{Built with ❤️ by the NextBlock™ Team. Licensed under AGPLv3.}