How NextBlock Works: A Look Under the Hood
How NextBlock Works: Architecture for a Visual-First CMS
NextBlock is purpose-built to feel like a polished product from day one, and that polish starts with the Nx monorepo. Applications and libraries sit side-by-side so the same code that powers the hosted CMS experience also ships inside the open-source template and CLI. Instead of scattering configuration across projects, TypeScript paths, Tailwind presets, and shared lint rules all originate from the workspace root, which keeps every downstream package aligned.
Monorepo Layout and Dependency Flow
The apps/nextblock directory contains the production Next.js interface—both the public site and the authenticated CMS. The apps/create-nextblock CLI mirrors it, syncing files from the main app before publishing a scaffolding tool. Reusable primitives live under libs/. UI components and design tokens are exported from @nextblock-cms/ui, cross-cutting helpers (translations, R2 clients, Supabase environment guards) live in @nextblock-cms/utils, and database code plus migrations are centralized inside @nextblock-cms/db. Future-facing work, like the SDK and e-commerce module, already have dedicated libraries so they can mature without disrupting the core runtime.
This organization matters because Nx understands project boundaries. When you run nx graph you see exactly how a change in the editor package might ripple into the Next.js app. Path aliases from tsconfig.base.json and the shared tailwind.config.js ensure that every consumer sees the same theme scales and helper utilities, which is crucial for a system that promises design parity between marketing pages, admin screens, and scaffolded customer projects.
Together, those guardrails mean features can ship quickly without regressions. Schema migrations live in libs/db, UI primitives live in libs/ui, and the CLI simply syncs changes downstream—no copy/paste debt, no drifting configs.
Inside the CMS Application
Within apps/nextblock/app/cms, each feature area—pages, posts, media, navigation, users, settings—follows a predictable file pattern: a list page, creation and edit routes, server actions, and scoped client components. The root CMS layout enforces authentication, builds the shell (sidebar, responsive header, profile menu), and injects role-aware navigation. That means writers can jump straight into the block editor while admins unlock additional menus such as language management or user provisioning, all without duplicating layout logic.
Server actions wrap Supabase calls so mutations never leak credentials into the browser. Media uploads coordinate with Cloudflare R2, navigation management includes drag-and-drop ordering, and every table interaction respects the row-level security policies defined in the Supabase migrations—e.g., only admins and writers can mutate pages or posts while anonymous traffic can only read published content.
Tech Stack and Runtime
The stack highlighted in the project README—Next.js 16, Supabase, Tailwind CSS, and shadcn/ui—was selected to balance developer velocity with runtime performance. Next.js App Router unlocks Server Components, streaming, and incremental static regeneration so marketing experiences remain edge-fast. Supabase covers Postgres, Auth, and Storage, shrinking the operational footprint while still allowing custom SQL migrations. Tailwind plus shadcn/ui provide composable building blocks so the CMS interface, marketing site, and generated client projects all inherit the same visual language.
Nx tooling ties it together. Common commands such as nx serve nextblock, nx build nextblock, or workspace-wide tasks like nx run-many -t lint --all respect dependency caching, so even large rebuilds feel snappy during the 100-day roadmap.
nx serve nextblock
nx run-many -t build --all
supabase db push
The Tiptap-Based Block Editor
The @nextblock-cms/editor package turns Tiptap v3 into a polished, reusable editing surface. It ships rich-text formatting, tables, task lists, slash commands, floating and bubble menus, character counts, focus mode, and syntax-highlighted code blocks. Under the hood it bundles StarterKit, TextStyleKit, CodeBlockLowlight, Image, TaskList, Table, Link, TextAlign, Highlight, Typography, and more. Because the editor is published as a standalone library, both the CMS and the generated template pull identical behavior, ensuring content parity.
From an implementation standpoint, the editor exposes granular components—EditorToolbar, BubbleMenu, FloatingMenu—so the CMS can embed one cohesive editing experience while keeping the door open for agencies or plugin developers to compose their own UI. Comprehensive CSS hooks (e.g., .tiptap pre for code blocks) mean that teams can layer in dark-mode friendly themes without forking the core package.
Putting It All Together
The result is a platform where architecture decisions reinforce each other: the Nx workspace keeps libraries honest, the Next.js app enforces UX consistency, Supabase migrations codify access rules, and the Tiptap editor guarantees that content collaborators see the same tooling regardless of deployment. When a new team runs npm create nextblock, they inherit not just a starter site, but the entire operational philosophy described above—ready to extend with SDKs, premium modules, and marketplace blocks as the ecosystem grows.