Skip to content

Building a CMS with Next.js, Supabase, Tailwind CSS, and AI Agents

Frank Mendez·
supabase nextjs

How I built a full-stack blog CMS with AI coding agents: the architecture, rich-text editor, secure publishing, media library, authentication, newsletters, integrations, testing, and deployment behind The Practical Engineer.

I wanted a blog that I could manage through a proper writing interface. Having worked with WordPress, I was familiar with the experience I wanted: write an article, organize it with categories and tags, add images, preview the result, and publish when it is ready. Building my own CMS became a practical way to learn how those familiar features work underneath.

This project brings together Next.js, React, TypeScript, Supabase, and Tailwind CSS. ChatGPT and Claude Code helped with planning and implementation. The interesting part was connecting the pieces into a system that protects drafts, respects ownership, handles failures, and gives authors a predictable publishing experience.

This walkthrough describes the repository implementation reviewed in October 2026. Some integrations require separate provider configuration, so code support should not be confused with proof that every hosted integration is enabled.

From the original launch to the current CMS

In my original DEV launch article, I introduced an open-source CMS built around authentication, roles, visual editing, and a developer-friendly stack. This article follows that introduction with the implementation details and the project’s evolution. Comments and richer SEO support are now implemented. The earlier standalone AI assistant and headless Developer API have since been retired, so the launch article should be read as a snapshot of that earlier version.

Planning the CMS with coding agents

The early discussions focused on the features, database structure, application boundaries, and user journey. I used ChatGPT for architectural discussions and planning, alongside Claude Code for development. My original workflow included Luna with extra-high reasoning for planning and Astra for coding. The lasting lesson is the division of work: use the agent to explore and implement, while keeping requirements, review, and verification explicit.

The repository gives agents a shared starting point through AGENTS.md, with CLAUDE.md importing the same instructions. Those instructions describe the architecture, commands, branch conventions, privacy rules, and publication safeguards. Project skills add focused guidance for React, composition, shadcn/ui, Tailwind, PostgreSQL, accessibility, Vitest, and browser verification.

Optional Model Context Protocol integrations connect development tools to GitHub, Supabase, Vercel, the filesystem, and a browser. A PostgreSQL integration can help investigate queries. These are development capabilities; the deployed CMS does not require an MCP server to serve an article. Keeping that distinction clear also helps limit which credentials an agent needs.

A useful task is specific enough to verify. For example, “add draft recovery” becomes: preserve unsaved fields, keep recovery copies private, identify the writer and document, detect stale changes, and restore without publishing. That gives both the agent and the reviewer concrete behavior to check.

The architecture: one application, clear responsibilities

Next.js App Router provides the public website, authenticated dashboard, settings screens, and internal HTTP handlers in one application. React handles interactive interfaces, and TypeScript describes the data and component contracts. Server-side code performs privileged operations; client components handle editing, forms, dialogs, and feedback.

  • app/ contains routes, layouts, and API handlers.

  • features/ groups domain logic such as posts, authentication, profiles, comments, onboarding, and reactions.

  • components/ contains the editor, dashboard components, and shared UI.

  • lib/ contains Supabase clients, permission helpers, analytics policies, and shared utilities.

  • supabase/migrations/ records ordered database changes; database/ contains supporting SQL and database assertions.

A typical write moves from a React form to an authenticated server action or internal handler, then into PostgreSQL through Supabase. The server validates the request and checks permission before performing the mutation. Database constraints and transaction functions enforce the rules that must hold even when requests arrive concurrently.

The technology stack and what each part does

The reviewed package manifest uses Next.js 16, React 19, TypeScript 6, Tailwind CSS 4, and TipTap 3. The project pins Node.js 24.21.0 and pnpm 10.29.3 for development. Exact dependency versions belong in package.json and pnpm-lock.yaml; they will change as the project evolves.

  • Next.js, React, and TypeScript: routing, rendering, server actions, interactive components, and typed application code.

  • Supabase: PostgreSQL persistence, Auth, and object Storage. The JavaScript and SSR packages support browser access and cookie-based server sessions.

  • Tailwind CSS, PostCSS, and the typography plugin: responsive layout, styling, and readable article typography. shadcn/ui and Base UI provide the component foundation. Class Variance Authority, clsx, and tailwind-merge support component variants and class composition.

  • TipTap and ProseMirror: structured rich-text editing. Extensions cover text styles, links, images, lists, task lists, tables, alignment, highlighting, typography, and character counts.

  • React Hook Form, Zod, and the resolver package: form state and runtime validation across writing, authentication, profiles, and other inputs.

  • Zustand: shared taxonomy state, including optimistic category/tag changes with rollback behavior.

  • Sharp and sanitize-html: server-side image processing and sanitization of supported legacy HTML content.

  • Resend: newsletter delivery and administrative email notifications.

  • Lucide React, Sonner, next-themes, nextjs-toploader, and tw-animate-css: icons, toast feedback, theme support, navigation progress, and UI animation utilities. date-fns handles date formatting, while slugify helps produce URL-friendly names.

  • OpenAI, Anthropic, and Google GenAI SDKs: provider integrations retained for owner-managed credential verification and future assistance work. Their presence does not mean full-post generation is currently available.

  • Vitest, Vite, Testing Library, jsdom, and Playwright: unit, component, browser, and integration verification. V8 and Monocart support coverage reporting.

  • ESLint, Husky, lint-staged, GitHub Actions, and Release Please: local checks, automated validation, and release management. Docker and the Supabase CLI provide an isolated local backend; Vercel hosts the application and its scheduled newsletter invocation.

Supporting packages such as server-only, dotenv, YAML tooling, and TypeScript type declarations help enforce server boundaries, load local configuration, inspect automation files, and type the toolchain. They support the application rather than adding separate user-facing features.

Authentication is more than a login form

Supabase Auth supplies email/password authentication and Google/GitHub sign-in. OAuth provider credentials are configured with Supabase, and the application handles its own callback and validated return destination. The social flow uses PKCE, verifies the returned user and identity, and checks MFA assurance before granting access to protected work.

The CMS has Author and Admin roles. Authors work within their own content permissions; administrators have broader management capabilities. A role comes from trusted database state, not a name or role string supplied by an OAuth provider or editable user metadata. Authentication establishes identity; authorization decides what that identity can do.

The account flows also cover email confirmation, resend, password recovery, MFA challenges, and session sign-out. Recovery has its own checks rather than being treated as an ordinary logged-in edit. Sensitive operations use the shared assurance requirements.

New eligible users complete onboarding for their profile name, professional background, discovery source, and interests. Progress is saved between steps and can resume later. Professional background and interests remain private, and selecting an interest does not subscribe someone to the newsletter or change their permission role.

PostgreSQL, ownership, and private data

Supabase combines several services, but PostgreSQL remains the source of truth for posts, relationships, profiles, reactions, working copies, and delivery state. Ordered SQL migrations capture how that schema evolves. Applying the full migration history matters because an old schema snapshot cannot reproduce newer permissions, functions, constraints, or triggers.

Row-level security and narrow database functions help restrict access. Public pages use a limited author-profile projection instead of exposing private profile records. Onboarding answers and recovery copies do not become public just because their owner publishes an article.

The server-only service-role client can bypass RLS. For that reason, privileged application code must explicitly check identity, ownership, role, and assurance before accessing data. Hiding a dashboard button is useful interface behavior, but it is not an authorization boundary.

Building the writing experience

The editor uses TipTap on top of ProseMirror to represent an article as structured content. Authors can format paragraphs and headings, add links and images, and use the available list and text-style controls. The application shares article rendering between the private preview and the public reader view. Legacy HTML is sanitized before it enters supported rendering and preview paths.

React Hook Form manages post fields, with Zod handling input validation. Title, slug, excerpt, content, taxonomy, cover details, and SEO metadata belong to one writing workflow. Optional settings remain out of the way until needed, and save failures keep the author's input available.

The editor also requests native English browser spellcheck. Spelling suggestions depend on the browser, installed dictionary, and user settings. That is separate from an application AI service.

Draft recovery and safe saves

Recovery combines browser localStorage with private server working copies. A recovery record includes the account, document, and writer identity, along with the fields and their saved baseline. Debounced autosave avoids sending a request for every keystroke, while visible save status tells the author whether the working copy has reached the server.

This distinction matters: a private working copy protects interrupted writing; Save Draft persists a draft post; Publish changes public state. Preview can show current unsaved input without saving or exposing a public preview URL.

Concurrency is another part of the writing experience. If two tabs edit the same post, a stale save should not silently replace newer work. The implementation compares saved versions and requires recovery or review when a conflict occurs. Creation also retains a stable recovery identity so a lost response does not casually create a duplicate article.

Post persistence uses the server-only save_post_atomic database function. Post fields, taxonomy relationships, URL reservations, and publication state commit together. If part of the operation fails, the save rolls back. Newsletter scheduling and cache refresh happen after successful persistence.

Publishing and protecting article URLs

Publication has a shared server-side policy: a descriptive title of 10–160 readable characters, a valid unique slug, a 40–500 character excerpt, at least 200 readable body words, and an identified author. Obvious filler and placeholder images are rejected. These are minimum checks; they cannot establish whether an article is accurate or useful.

A human must confirm editorial review before publication or live edits. Editing clears that confirmation. AI-assisted writing follows the same rule, so an agent cannot declare the article reviewed on the author's behalf.

Published URLs are treated as durable identifiers. Changing a title preserves an existing slug. Deliberately changing a published URL reserves the old address and redirects it to the current published address with a 308 response. Unpublishing makes the article unavailable while keeping its reservations, preventing a different post from taking over its historical URL.

For example, an article published at /blog/building-a-cms should not move just because its title becomes more descriptive. If its URL is intentionally changed later, existing links should still lead to that same article.

Images and the owner-scoped media library

Image handling starts with server-side validation of actual bytes. Sharp decodes accepted non-animated JPEG, PNG, and WebP files, normalizes orientation, strips metadata, resizes within the configured limits, and produces WebP output. The current pipeline accepts inputs up to 4 MiB and 40 megapixels, limits dimensions to 2400 pixels per side, and requires optimized output to fit within 2 MiB.

Supabase Storage holds immutable objects. A SHA-256 hash of the optimized bytes allows identical content to be reused within the same owner's library, even when a filename changes. Registry metadata tracks readiness and retention so concurrent uploads, retries, saves, and cleanup do not overwrite an object unexpectedly.

The media library supports search, sorting, metadata editing, archive/restore, and selection into cover or inline image dialogs. Default alt text and dimensions are copied into the selected occurrence; editing library metadata does not silently rewrite existing articles.

Ownership protects library management, but the stored article images are public to anyone who has their URL, including when used in drafts. That makes them suitable for publication assets, not confidential files. Referenced media is retained conservatively; never-referenced editor uploads have a grace period before cleanup eligibility.

Taxonomy, discovery, and reader interaction

Categories and tags organize content across public pages and the dashboard. Tag selection is searchable, and administrative merges preserve aliases so old tag URLs continue to resolve. Dashboard filtering, sorting, pagination, and search live in URL state, making a view easier to revisit or share with another authorized administrator.

Public listings fetch summary fields rather than full article bodies. Reading time is derived from readable content in the database. Article metadata and page rendering share request-scoped reads, while publication changes invalidate the relevant public routes and sitemap.

Comments and reactions give readers ways to participate. Article reactions allow multiple independent types per reader; comment reactions allow one selected type per reader/comment. Mutations set the desired state explicitly, so retrying a lost response does not accidentally toggle the action back.

Reaction counts refresh on focus, visibility changes, and a visible-page interval. This implementation uses periodic reads rather than Supabase Realtime subscriptions. Database functions return aggregate counts and the current viewer's selection without exposing lists of private reactor identities.

Resend newsletters, Vercel Cron, and webhooks

Newsletter delivery connects PostgreSQL, Vercel Cron, and Resend. Readers opt in through the subscription form. Publishing queues a notification with an earliest eligible send time. A scheduled dispatcher claims due work and sends through Resend to active subscribers.

The configured daily cron runs at 09:00 UTC, or 17:00 in Manila, while the default publication delay is 60 minutes. Those settings describe different things: the delay controls eligibility, and the next dispatcher run controls when delivery can begin. Publishing at noon does not promise an email exactly one hour later.

The queue records preparation and provider handoff separately. Unpublishing cancels eligible pending work; messages already handed to the provider cannot be recalled. Retries must avoid restarting a notification that might already have reached recipients. A newsletter scheduling failure is surfaced separately from a successful article save.

Each email includes an unsubscribe link. The administrator interface exposes subscriber and send information, while dispatch endpoints require their configured server-side secrets.

A separate Supabase database webhook handles the transition to a confirmed user profile. The application validates the webhook secret and event, then can notify an administrator through Resend and a Slack incoming webhook. This is an operational notification path, distinct from reader subscriptions. It requires provider and webhook setup outside the source repository.

SEO and consent-aware analytics

The CMS supports article SEO fields, title/excerpt fallbacks, canonical URLs, taxonomy pages, public author profiles, and a sitemap. Redirect reservations connect publishing behavior with search reliability: renaming an article should not break its existing inbound links.

The Google Analytics integration has explicit deployment and consent gates. It requires an enabled production configuration and the canonical origin. It limits collection to eligible public routes and sanitizes locations and referrers, excluding private dashboard and authentication URLs. Free-text search is not transmitted as a query value.

The application owns the intended events, including newsletter subscription outcomes. Property configuration and live verification remain separate rollout tasks; adding a measurement ID to a file is not sufficient proof of correct collection.

What happened to the AI features?

Using coding agents to build the CMS is different from putting content-generation tools inside it. Earlier versions explored standalone PDF extraction, book chat, full-post generation, and an external Developer API. Those entry points have been retired and return 410 API_RETIRED.

The current AI Providers settings let each author manage their own encrypted provider credentials. Keys use AES-256-GCM, are never returned in plaintext, and are not replaced by environment-key fallbacks. Verification makes a bounded model-list request; it does not generate an article automatically. Administrators cannot manage another author's provider keys through these settings.

Existing legacy AI data remains private under the retention policy. Editor assistance is separate future work. Describing the SDK dependencies as a working full-post generator would misrepresent the current project.

Testing, deployment, and releases

Unit and component tests use Vitest, Testing Library, and jsdom. Playwright covers browser flows and application/API behavior. SQL assertions and concurrency tests exercise the database rules that mocks cannot prove, including permissions, atomic saves, URL reservations, and competing writes.

Local Supabase runs through Docker. Test databases must be disposable or explicitly designated for testing, with external mail and webhooks disabled. A mocked OAuth callback can verify application handling, but it cannot prove that a real Google or GitHub provider is configured correctly.

GitHub Actions validates changes according to their scope. Application changes receive the full checks; narrowly classified documentation changes can use lighter validation. The CI gate checks the required job outcomes. Main and develop pushes retain full verification baselines, while ordinary feature-branch pushes rely on a PR or manual CI dispatch.

Work normally branches from develop and returns through a pull request. Production promotion merges develop into main, with synchronization back afterward. Release Please manages stable releases on main, and Vercel provides the deployment target. Database migrations must be applied in the required order before dependent application code is deployed; some media or newsletter migrations require a coordinated pause and handoff.

For local development, the basic sequence is to select the pinned Node version, install with pnpm install --frozen-lockfile, start local Supabase, apply migrations, configure local environment variables, and run pnpm run dev. Useful checks include pnpm run typecheck, pnpm run lint, pnpm run test:run, pnpm run build, and the appropriate Playwright and database suites.

What this project taught me

Building a CMS exposes the engineering behind everyday authoring actions. A save button has to handle partial failure. An image library needs retention rules. A changed slug affects existing links. A newsletter needs an explicit boundary between queued work and an irreversible email handoff.

Next.js and React connect the public site and dashboard. Supabase provides the backend services, while PostgreSQL carries the consistency rules. Tailwind CSS and the component system make the interface manageable. Coding agents help turn a clear requirement into implementation, but the project still needs deliberate boundaries, tests, and human review.

For someone building a similar project, start with one complete journey: authenticate, write, save privately, preview, and publish a reviewed article. Then add media, taxonomy, reader interaction, notifications, and analytics with their failure cases included. That turns a learning project into a system whose behavior can be explained and verified.

Try it and explore the source

You can browse The Practical Engineer to see the reader experience or create an account to explore the author workflow. The project is open source under the MIT license. Fork it for your own experiments, inspect the migrations and tests, or contribute a focused issue or pull request. A useful contribution explains the expected behavior and how to reproduce or verify it.

Project references

The implementation and setup details are documented in the Next.js Blog CMS repository and its documentation index. For deeper implementation contracts, see the guides on publication and URL safety, images and media, newsletter delivery, and agent and MCP workflows.

Loading reactions…

Stay in the loop

Get notified when new posts are published. No spam, unsubscribe anytime.

No spam · Unsubscribe anytime

💬 Leave a Comment

Want to join the conversation?