But after running the same project on both platforms for about a week, I started exploring Cloudflare Workers as an alternative. I noticed improvements in latency (lower TTFB) and found the free tier to be more flexible for my use case.

Deploying Next.js apps on Cloudflare used to be challenging. Earlier solutions like Cloudflare Pages had limitations with full Next.js features, and tools like next-on-pages often lagged behind the latest releases.

That changed with the introduction of @opennextjs/cloudflare. It allows you to compile a standard Next.js application into a Cloudflare Worker, supporting features like SSR, ISR, middleware, and the Image component – all without requiring major code changes.

In this guide, I’ll walk you through the exact steps I used to deploy my full-stack Next.js + Supabase application to Cloudflare Workers.

This article is the runbook I wish I had when I started.

Table of Contents

• Why Choose Cloudflare Workers Over Vercel?

• Prerequisites

• The Stack

• Step 1 — Install the Cloudflare Adapter

• Step 2 — Wire OpenNext into next dev

• Step 3— Local Environment Setup with .dev.vars

• Step 4 — Deploy Your App from Your Local Machine

• Step 5 — Push your secrets to the Worker

• Step 6 — Set Up Continuous Deployment with GitHub Actions

• Step 7 — Updating the project (the daily workflow)

• Final thoughts

Why Choose Cloudflare Workers Over Vercel?

When deploying a Next.js application, Vercel is often the default choice. It offers a smooth developer experience and tight integration with Next.js.

But Cloudflare Workers provides a compelling alternative, especially when you care about global performance and cost efficiency.

Here’s a high-level comparison (at the time of writing):

Key Takeaways

• Lower latency globally: Cloudflare runs your app across hundreds of edge locations, reducing response time for users worldwide.

• Minimal cold starts: Thanks to V8 isolates, functions start almost instantly.

• Cost efficiency: The free tier is generous enough for portfolios, blogs, and many small-to-medium apps.

Trade-offs to Consider

Cloudflare Workers use a V8 isolate runtime, not a full Node.js environment. That means:

• Some Node.js APIs like fs or child_process aren't available

• Native binaries or certain libraries may not work

That said, for most modern stacks – like Next.js + Supabase + Stripe + Resend – this limitation is rarely an issue.

In short, choose Vercel if you want the simplest, plug-and-play Next.js deployment. Choose Cloudflare Workers if you want better edge performance and more flexible scaling.

Prerequisites

Before getting started, make sure you have the following set up. Most of these take only a few minutes:

• Node.js 18+ and pnpm 9+ (you can also use npm or yarn, but this guide uses pnpm.)

• A Cloudflare account 👉 https://dash.cloudflare.com/sign-up

• A Supabase account (if your app uses a database) 👉 https://supabase.com

• A GitHub repository for your project (required later for CI/CD setup)

• A domain name (optional) – You’ll get a free *.workers.dev URL by default.

Install Wrangler (Cloudflare CLI)

We’ll use Wrangler to build and deploy the application:

pnpm add -D wrangler

The Stack

Here’s the tech stack used in this project:

• Next.js (v14.2.x): Using the App Router with Edge runtime for both public and dashboard routes

• Supabase: Handles authentication, Postgres database, and Row-Level Security (RLS)

• Tailwind CSS + UI utilities: For styling, along with lightweight animation using Framer Motion

• Cloudflare Workers: Deployment powered by @opennextjs/cloudflare and wrangler

• GitHub Actions: Used to automate CI/CD and deployments

Note: If you're using Next.js 15 or later, you can remove the
--dangerouslyUseUnsupportedNextVersion flag from the build script, as it's only required for certain Next.js 14 setups.

Step 1 — Install the Cloudflare Adapter

From inside your existing Next.js project, install the OpenNext adapter along with Wrangler (Cloudflare’s CLI tool):

pnpm add @opennextjs/cloudflare
pnpm add -D wrangler

Then add the deploy scripts to package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",

    "cloudflare-build": "opennextjs-cloudflare build --dangerouslyUseUnsupportedNextVersion",
    "preview":          "pnpm cloudflare-build && opennextjs-cloudflare preview",
    "deploy":           "pnpm cloudflare-build && wrangler deploy",
    "upload":           "pnpm cloudflare-build && opennextjs-cloudflare upload",
    "cf-typegen":       "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
  }
}

What each script does:

Heads up: the Pages-based @cloudflare/next-on-pages is a different tool. We are not using Pages — we're deploying as a real Worker. Don't mix the two.

Step 2 — Wire OpenNext into next dev

So that pnpm dev can read your Cloudflare bindings (env vars, R2, KV, D1, …) the same way production will, edit next.config.mjs:

/** @type {import('next').NextConfig} */
const nextConfig = {};

if (process.env.NODE_ENV !== "production") {
  const { initOpenNextCloudflareForDev } = await import(
    "@opennextjs/cloudflare"
  );
  initOpenNextCloudflareForDev();
}

export default nextConfig;

We only call it in development so next build stays fast and CI doesn't spin up a Miniflare instance for nothing.

Step 3 — Local Environment Setup with .dev.vars

When working with Cloudflare Workers locally, Wrangler uses a file called .dev.vars to store environment variables (instead of .env.local used by Next.js).

A simple and reliable approach is to keep an example file in your repo and ignore the real one.

Example: .dev.vars.example (committed)

NEXT_PUBLIC_SUPABASE_URL="https://YOUR-PROJECT-ref.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="YOUR-ANON-KEY"
NEXT_PUBLIC_DASHBOARD_DEFAULT_EMAIL="admin@example.com"

Set Up Your Local Environment

Run the following commands:

cp .dev.vars.example .dev.vars
cp .dev.vars .env.local

• .dev.vars is used by Wrangler (wrangler dev)

• .env.local is used by Next.js (next dev)

Why Use Both Files?

• next dev reads from .env.local

• wrangler dev (used in pnpm preview) reads from .dev.vars

Keeping both files in sync ensures your app behaves consistently in development and when running in the Cloudflare runtime.

Update .gitignore

Make sure these files are ignored:

.dev.vars
.env*.local
.open-next
.wrangler

Step 4 — Deploy Your App from Your Local Machine

Once pnpm preview is working correctly, you're ready to deploy your application:

pnpm deploy

Under the hood that runs:

pnpm cloudflare-build && wrangler deploy

The first time, Wrangler will:

1. Compile your app to .open-next/worker.js.

2. Upload the script + assets to Cloudflare.

3. Print your live URL, e.g. https://porfolio.<your-account>.workers.dev.

Open it in a browser. Congratulations — you're on Cloudflare's edge in 330+ cities. The page should be served in <100 ms TTFB from anywhere.

Here's the live version of my own portfolio deployed this way

Step 5 — Push Your Secrets to the Worker

Local .dev.vars is not uploaded by wrangler deploy. You have to push secrets explicitly:

wrangler secret put NEXT_PUBLIC_SUPABASE_URL
wrangler secret put NEXT_PUBLIC_SUPABASE_ANON_KEY
wrangler secret put NEXT_PUBLIC_DASHBOARD_DEFAULT_EMAIL

Each command prompts you for the value and stores it encrypted on Cloudflare. Or do it visually:

Cloudflare Dashboard → Workers & Pages → your worker → Settings → Variables and Secrets → Add.

Important: NEXT_PUBLIC_* vars are inlined into the client bundle at build time, so they also need to be available when pnpm cloudflare-build runs (locally, that's your .env.local; in CI, see Step 10).

Step 6 — Set Up Continuous Deployment with GitHub Actions

Once your local deployment is working, the next step is automating deployments so every push to the main branch updates production automatically.

With this workflow:

• Pull requests will run validation checks

• Production deploys only happen after successful builds

• Broken code never reaches your live site

Create the following file inside your project:

.github/workflows/deploy.yml

name: CI / Deploy to Cloudflare Workers

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

concurrency:
  group: cloudflare-deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  verify:
    name: Lint and Build
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 10

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm build
        env:
          NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.NEXT_PUBLIC_SUPABASE_URL }}
          NEXT_PUBLIC_SUPABASE_ANON_KEY: ${{ secrets.NEXT_PUBLIC_SUPABASE_ANON_KEY }}
          NEXT_PUBLIC_DASHBOARD_DEFAULT_EMAIL: ${{ secrets.NEXT_PUBLIC_DASHBOARD_DEFAULT_EMAIL }}

  deploy:
    name: Deploy to Cloudflare Workers
    needs: verify
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 10

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      - run: pnpm install --frozen-lockfile

      - name: Build and Deploy
        run: pnpm run deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.NEXT_PUBLIC_SUPABASE_URL }}
          NEXT_PUBLIC_SUPABASE_ANON_KEY: ${{ secrets.NEXT_PUBLIC_SUPABASE_ANON_KEY }}
          NEXT_PUBLIC_DASHBOARD_DEFAULT_EMAIL: ${{ secrets.NEXT_PUBLIC_DASHBOARD_DEFAULT_EMAIL }}

Required GitHub repo secrets

Go to GitHub repo → Settings → Secrets and variables → Actions → New repository secret and add:

That's it. Push it to main and it'll go live in about 90 seconds. PRs run lint and build only, so broken code never reaches production.

Step 7 — Updating the Project (the Daily Workflow)

After the initial setup, the loop is boringly simple — which is the whole point. Here's what I actually do day-to-day:

Code Change

git checkout -b feat/new-section
# ...edit files...
pnpm dev                # iterate locally
pnpm preview            # final smoke test on the Worker runtime
git commit -am "feat: add new section"
git push origin feat/new-section

Open a PR and the verify that the job runs. Then review, merge, and the deploy it. The job ships to Cloudflare automatically.

Updating env Vars / Secrets

# Local
nano .dev.vars

# Production
wrangler secret put NEXT_PUBLIC_SUPABASE_URL
# ...etc.

Final Thoughts

When I started this migration, I was nervous about leaving Vercel — the Next.js DX there is genuinely excellent. But the moment you push beyond a hobby site, Cloudflare's economics and edge performance are not close.

With @opennextjs/cloudflare, the developer experience has also caught up: my pnpm dev loop is identical, my pnpm preview mimics production, and git push deploys globally in ~90 seconds.

If you've been holding off because the old Cloudflare Pages + Next.js story was rough, that era is over. Try this runbook on a side project this weekend and see for yourself.

If you found this useful, the full repo is here — feel free to clone it as a starter.

Happy shipping.

— Tarikul

The answer is multi-tenancy: an architecture where one application dynamically serves isolated experiences to many different users, often through subdomains.

In this tutorial, you'll build a multi-tenant portfolio SaaS platform from scratch using Next.js, Express, and Prisma. Each user who signs up gets their own portfolio site, served on their own subdomain — generated instantly, powered by a single backend, and stored in a single database.

Here's what you'll build:

• A landing page where users fill out a form to create their portfolio

• An Express + Prisma backend that stores each user as a "tenant"

• A Next.js middleware layer that detects subdomains and routes requests dynamically

• A JSON-driven template system that controls which sections appear on each portfolio

• A production-ready portfolio page served at name.localhost:3000 in development and name.yourdomain.com in production

You can find the complete source code in the GitHub repositories linked at the end of this tutorial.

Table of Contents

• Prerequisites

• What is Multi-Tenancy?

• How to Set Up the Backend

  • How to Install Dependencies

  • How to Configure TypeScript for ESM

  • How to Initialize Prisma

• How to Define the Prisma Schema

• How to Run Your First Migration

• How to Generate and Instantiate the Prisma Client

  • How to Generate the Client

  • How to Instantiate the Client

• How to Seed a Template

• How to Build the Express API

  • How to Install Express

  • How to Create the Server Entry Point

  • How to Create the Express App

  • How to Create the Tenant Controller

  • How to Create the Tenant Routes

  • How to Start the Server

• How to Create the Next.js Frontend

• How to Add Subdomain Routing with Middleware

• How to Build the Landing Page

  • How to Update the Layout

  • How to Create the Home Page

• How to Build the Tenant Portfolio Page

• How to Test the Full Flow

• Next Steps

• Conclusion

• Source Code

Prerequisites

Before you begin, make sure you have the following:

• Node.js (version 18 or higher) installed on your machine

• A basic understanding of React, TypeScript, and REST APIs

• Familiarity with Prisma ORM (you don't need to be an expert)

• A code editor like VS Code

You'll use Prisma Postgres as your database, so you won't need to set up a separate database server locally. Prisma handles the connection string and adapter configuration for you.

What is Multi-Tenancy?

Multi-tenancy is an architectural pattern where a single application serves multiple users — called tenants — each with isolated data and often their own URL.

Here's how the flow works in this tutorial:

1. A user visits your landing page and fills out a form with their name, bio, and skills.

2. Your Express backend creates a new tenant record in the database and generates a slug from their name.

3. The browser redirects the user to their-name.localhost:3000.

4. Your Next.js middleware detects the subdomain, extracts the slug, and rewrites the request to /tenant/their-name internally.

5. The tenant page fetches that user's data from the API and renders their portfolio.

The key insight is that the URL in the browser never changes — the rewrite is invisible to the user. One Next.js app serves every tenant dynamically.

How to Set Up the Backend

Start by creating a project folder with separate directories for the backend and frontend:

mkdir portfolio-saas && cd portfolio-saas
mkdir portfolio-api portfolio-client

Navigate into the backend directory and initialize a new Node.js project:

cd portfolio-api
npm init -y

How to Install Dependencies

Install TypeScript, Prisma, and the supporting packages:

npm install typescript tsx @types/node --save-dev
npx tsc --init
npm install prisma @types/node @types/pg --save-dev
npm install @prisma/client @prisma/adapter-pg pg dotenv

How to Configure TypeScript for ESM

Open tsconfig.json and replace its contents with:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2023",
    "strict": true,
    "esModuleInterop": true,
    "ignoreDeprecations": "6.0",
    "types": ["node"]
  }
}

Then open package.json and add "type": "module" to enable ESM:

{
  "type": "module"
}

How to Initialize Prisma

Run the following command to initialize Prisma and generate your schema setup:

npx prisma init --db --output ../generated/prisma

This command creates a prisma/schema.prisma file, a .env file with your database connection string, and a generated Prisma configuration folder.

How to Define the Prisma Schema

Open prisma/schema.prisma and replace its contents with the following:

generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider = "postgresql"
}

model Tenant {
  id         String   @id @default(uuid())
  slug       String   @unique
  name       String
  bio        String
  skills     String[]
  templateId String
  createdAt  DateTime @default(now())
}

model Template {
  id     String @id @default(uuid())
  name   String
  config Json
}

model Post {
  id         String   @id @default(uuid())
  title      String
  content    String
  tenantSlug String
  createdAt  DateTime @default(now())
}

Let's look at what each model does.

The Tenant model represents a user who has signed up and created a portfolio. The slug field is generated from their name (for example, "John Doe" becomes john-doe) and is used as their subdomain. The templateId links each tenant to a template that controls their portfolio's layout.

The Template model stores layout configuration as JSON. Instead of hardcoding sections like "hero" or "skills" into your components, you store them in the database. This means you can add or remove sections for different templates without touching any component code.

The Post model is included for future extensibility — you can use it to let tenants publish blog posts on their portfolio.

How to Run Your First Migration

Run the following command to create your database tables based on the schema:

npx prisma migrate dev --name init

This command creates the database tables, generates a migration file, and applies the migration to your database. After it runs, your Postgres database structure matches your Prisma schema exactly.

How to Generate and Instantiate the Prisma Client

How to Generate the Client

Run this command to generate a fully type-safe Prisma Client based on your schema:

npx prisma generate

You only need to run this once after each schema change. The generated client lives in the ../generated/prisma folder you configured earlier.

How to Instantiate the Client

Create a new file at lib/prisma.ts and add the following:

import 'dotenv/config';
import { PrismaPg } from '@prisma/adapter-pg';
import { PrismaClient } from '../generated/prisma/client';

const connectionString = process.env.DATABASE_URL as string;

const adapter = new PrismaPg({ connectionString });
const prisma = new PrismaClient({ adapter });

export default prisma;

This file creates a single shared Prisma Client instance that your entire backend will import. The PrismaPg adapter connects Prisma to your Postgres database using the connection string from your .env file.

How to Seed a Template

Your platform needs at least one template in the database before any tenant can sign up. Instead of hardcoding layout decisions into your components, you'll store the template configuration as JSON and read it at runtime.

Create a new file at prisma/seed.ts and add the following:

import prisma from '../lib/prisma';

async function main() {
  await prisma.template.create({
    data: {
      name: 'minimal',
      config: {
        theme: {
          primaryColor: '#6366f1',
          background: 'dark',
        },
        sections: {
          hero: true,
          about: true,
          skills: true,
          projects: true,
          blog: true,
          contact: true,
        },
      },
    },
  });

  console.log('Template seeded successfully.');
}

main()
  .catch((e) => {
    console.error(e);
    process.exit(1);
  })
  .finally(async () => {
    await prisma.$disconnect();
  });

The config field is stored as JSON in Postgres. When a tenant's portfolio loads, your frontend reads this JSON to decide which sections to show. Setting hero: false on a template would hide the hero section for every tenant using that template — no code changes needed.

Now add a seed script to your package.json:

{
  "scripts": {
    "seed": "tsx prisma/seed.ts"
  }
}

Run it:

npm run seed

Your database now has a default template ready to attach to new tenants.

How to Build the Express API

Now you'll build the backend API that creates tenants and retrieves their data.

How to Install Express

npm install express cors
npm install -D @types/express @types/cors

How to Create the Server Entry Point

Create src/index.ts:

import app from './app';

const PORT = 8080;

app.listen(PORT, () => {
  console.log('Server is running on port 8080');
});

How to Create the Express App

Create src/app.ts:

import express from 'express';
import cors from 'cors';
import tenantRoutes from './routes/tenant.routes';

const app = express();

app.use(cors());
app.use(express.json());
app.use('/api', tenantRoutes);

export default app;

This file sets up CORS so your Next.js frontend can communicate with the API, parses JSON request bodies, and mounts all tenant routes under the /api prefix.

How to Create the Tenant Controller

Create src/controllers/tenant.controller.ts:

import { Request, Response } from 'express';
import prisma from '../../lib/prisma';

export async function createTenant(req: Request, res: Response) {
  const { name, bio, skills } = req.body;

  if (!name || !bio || !skills) {
    return res.status(400).json({ error: 'Missing required fields' });
  }

  const slug = name.toLowerCase().replace(/\s+/g, '-');

  const template = await prisma.template.findFirst();
  if (!template) {
    return res.status(500).json({ error: 'No template found' });
  }

  const tenant = await prisma.tenant.create({
    data: {
      slug,
      name,
      bio,
      skills,
      templateId: template.id,
    },
  });

  res.json({ slug: tenant.slug });
}

export async function getTenant(req: Request, res: Response) {
  const slug = req.params.slug;

  if (!slug || typeof slug !== 'string') {
    return res.status(400).json({ error: 'Invalid slug parameter' });
  }

  const tenant = await prisma.tenant.findUnique({
    where: { slug },
  });

  if (!tenant) {
    return res.status(404).json({ error: 'Tenant not found' });
  }

  const template = await prisma.template.findUnique({
    where: { id: tenant.templateId },
  });

  res.json({ tenant, template });
}

Let's break down what this controller does.

createTenant takes the user's name, bio, and skills from the request body. It generates a slug by lowercasing the name and replacing spaces with hyphens — so "Jane Smith" becomes jane-smith. It then finds the first available template and creates the tenant record in the database, linking the template to the new tenant via templateId.

getTenant looks up a tenant by their slug and also fetches the template attached to them. Both pieces of data are returned together so the frontend can render the portfolio and apply the correct layout configuration in a single API call.

How to Create the Tenant Routes

Create src/routes/tenant.routes.ts:

import { Router } from 'express';
import { createTenant, getTenant } from '../controllers/tenant.controller';

const router = Router();

router.post('/tenants', createTenant);
router.get('/tenants/:slug', getTenant);

export default router;

Your API now exposes two endpoints:

POST   /api/tenants        — creates a new tenant
GET    /api/tenants/:slug  — retrieves a tenant and their template

How to Start the Server

Add the dev script to your package.json:

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "seed": "tsx prisma/seed.ts"
  }
}

Run it:

npm run dev

You should see Server is running on port 8080 in your terminal. Your backend is ready.

How to Create the Next.js Frontend

Navigate to the portfolio-client directory and create a new Next.js project. Make sure to select Yes when the installer asks if you want to use Tailwind CSS:

cd ../portfolio-client
npx create-next-app@latest . --typescript --app --tailwind --eslint
npm install

Since create-next-app sets up Tailwind for you automatically, no extra configuration is needed. The tailwind.config.ts and the @tailwind directives in globals.css are already in place.

How to Add Subdomain Routing with Middleware

This is the heart of the multi-tenant architecture. You need a piece of code that runs before every request, reads the subdomain from the URL, and rewrites the request to the correct internal route — all without the user ever seeing the URL change.

Create a file called proxy.ts in the root directory:

import { NextRequest, NextResponse } from 'next/server';

export function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const host = request.headers.get('host') ?? '';

  const hostname = host.split(':')[0];
  const parts = hostname.split('.');

  // Local development: john.localhost:3000
  if (hostname.endsWith('localhost')) {
    const subdomain = parts[0];

    // Root localhost — load the landing page normally
    if (subdomain === 'localhost') {
      return NextResponse.next();
    }

    // Already rewritten — don't rewrite again
    if (pathname.startsWith('/tenant')) {
      return NextResponse.next();
    }

    return NextResponse.rewrite(new URL(`/tenant/${subdomain}`, request.url));
  }

  // Production: john.yourdomain.com
  if (parts.length > 2) {
    const subdomain = parts[0];

    if (subdomain !== 'www') {
      if (pathname.startsWith('/tenant')) {
        return NextResponse.next();
      }

      return NextResponse.rewrite(new URL(`/tenant/${subdomain}`, request.url));
    }
  }

  return NextResponse.next();
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|robots.txt|sitemap.xml).*)',
  ],
};

Here's exactly what this proxy does, step by step.

It reads the host header from every incoming request and splits it on . to extract the subdomain. For a request to john.localhost:3000, the subdomain is john. For a request directly to localhost:3000, the subdomain is localhost itself — in which case the proxy lets the request through unchanged so the landing page loads normally.

When a subdomain is detected, the proxy rewrites the request URL from / to /tenant/john internally. This rewrite is invisible to the browser — the user still sees john.localhost:3000 in their address bar, but Next.js routes the request to your /tenant/[slug] page.

The if (pathname.startsWith('/tenant')) guard prevents infinite rewrite loops. Without it, the already-rewritten request would be rewritten again on the next pass through the middleware.

How to Build the Landing Page

How to Update the Layout

Open app/layout.tsx and update it:

import type { Metadata } from 'next';
import { Geist, Geist_Mono } from 'next/font/google';
import './globals.css';

const geistSans = Geist({
  variable: '--font-geist-sans',
  subsets: ['latin'],
});

const geistMono = Geist_Mono({
  variable: '--font-geist-mono',
  subsets: ['latin'],
});

export const metadata: Metadata = {
  title: 'Portfolio SaaS App',
  description: 'Create and host your portfolio with subdomains',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={`\({geistSans.variable} \){geistMono.variable} antialiased`}>
        {children}
      </body>
    </html>
  );
}

How to Create the Home Page

Create app/page.tsx:

'use client';

import { useState } from 'react';

export default function Home() {
  const [name, setName] = useState('');
  const [bio, setBio] = useState('');
  const [skills, setSkills] = useState('');

  const handleSubmit = async () => {
    const res = await fetch('http://localhost:8080/api/tenants', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        name,
        bio,
        skills: skills.split(',').map((s) => s.trim()),
      }),
    });

    const data = await res.json();
    window.location.href = `http://${data.slug}.localhost:3000`;
  };

  return (
    <div className="min-h-screen bg-gradient-to-br from-slate-900 to-slate-800 text-white flex flex-col">
      {/* Header */}
      <header className="flex items-center justify-between px-10 py-5">
        <span className="text-xl font-semibold tracking-wide">PortfolioSaaS</span>
        <nav className="flex gap-6 text-sm text-slate-400">
          <a href="#features" className="hover:text-white transition-colors">Features</a>
          <a href="#pricing" className="hover:text-white transition-colors">Pricing</a>
          <a href="#docs" className="hover:text-white transition-colors">Docs</a>
        </nav>
      </header>

      {/* Main */}
      <main className="flex flex-1 items-center justify-center px-6 py-10">
        <div className="w-full max-w-md bg-slate-800 rounded-2xl p-10 shadow-2xl">
          <h1 className="text-3xl font-bold mb-3">Create Your Portfolio</h1>
          <p className="text-slate-400 text-sm mb-8">
            Launch your personal portfolio instantly with your own subdomain.
          </p>

          <input
            type="text"
            placeholder="Your Name"
            onChange={(e) => setName(e.target.value)}
            className="w-full bg-slate-900 border border-slate-700 rounded-lg px-4 py-3 text-sm text-white placeholder-slate-500 focus:outline-none focus:border-indigo-500 mb-4"
          />

          <textarea
            placeholder="Short Bio"
            rows={4}
            onChange={(e) => setBio(e.target.value)}
            className="w-full bg-slate-900 border border-slate-700 rounded-lg px-4 py-3 text-sm text-white placeholder-slate-500 focus:outline-none focus:border-indigo-500 mb-4 resize-none"
          />

          <input
            type="text"
            placeholder="Skills (comma separated)"
            onChange={(e) => setSkills(e.target.value)}
            className="w-full bg-slate-900 border border-slate-700 rounded-lg px-4 py-3 text-sm text-white placeholder-slate-500 focus:outline-none focus:border-indigo-500 mb-6"
          />

          <button
            onClick={handleSubmit}
            className="w-full bg-indigo-600 hover:bg-indigo-500 text-white font-semibold py-3 rounded-lg transition-colors"
          >
            Create Portfolio
          </button>
        </div>
      </main>

      {/* Footer */}
      <footer className="text-center text-xs text-slate-500 py-5 border-t border-slate-800">
        © {new Date().getFullYear()} PortfolioSaaS. All rights reserved.
      </footer>
    </div>
  );
}

When a user submits the form, three things happen in sequence. First, a POST request creates a new tenant in your database. Second, the API returns the generated slug. Third, the browser redirects the user to their subdomain — their-name.localhost:3000 — where the middleware takes over and renders their portfolio.

How to Build the Tenant Portfolio Page

Create app/tenant/[slug]/page.tsx:

import type { Metadata } from 'next';

async function getTenant(slug: string) {
  const res = await fetch(`http://localhost:8080/api/tenants/${slug}`, {
    cache: 'no-store',
  });
  return res.json();
}

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}): Promise<Metadata> {
  const { slug } = await params;
  const { tenant } = await getTenant(slug);

  if (!tenant) {
    return {
      title: 'Portfolio Not Found',
      description: 'This portfolio does not exist.',
      robots: { index: false, follow: false },
    };
  }

  return {
    title: tenant.name,
    description:
      tenant.bio?.slice(0, 160) ||
      `Explore ${tenant.name}'s professional portfolio.`,
    openGraph: {
      title: tenant.name,
      description: tenant.bio,
      type: 'website',
    },
  };
}

function initials(name: string) {
  return name
    .split(' ')
    .filter(Boolean)
    .slice(0, 2)
    .map((n) => n[0]?.toUpperCase())
    .join('');
}

export default async function TenantPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const data = await getTenant(slug);

  const tenant = data?.tenant;
  const template = data?.template;

  if (!tenant) {
    return (
      <div className="min-h-screen bg-slate-900 text-white flex items-center justify-center">
        <h1 className="text-2xl font-bold text-slate-400">Portfolio not found</h1>
      </div>
    );
  }

  const primary = template?.config?.theme?.primaryColor || '#6366f1';

  // Template-driven section toggles with safe defaults
  const sections = {
    hero: true,
    about: true,
    skills: true,
    projects: true,
    blog: true,
    contact: true,
    ...(template?.config?.sections ?? {}),
  };

  const avatarUrl = tenant.avatarUrl as string | undefined;

  return (
    <div className="min-h-screen bg-gradient-to-br from-slate-900 via-slate-800 to-slate-900 text-slate-100">

      {/* Header */}
      <header className="sticky top-0 z-20 backdrop-blur-md bg-slate-900/60 border-b border-white/5">
        <div className="max-w-5xl mx-auto px-5 py-4 flex items-center justify-between gap-4">
          <div className="flex items-center gap-3 min-w-0">
            <span
              className="w-2.5 h-2.5 rounded-full shrink-0"
              style={{ backgroundColor: primary }}
            />
            <span className="font-semibold truncate">{tenant.name}</span>
          </div>

          <nav className="hidden md:flex items-center gap-5 text-sm text-slate-400">
            {(sections.hero || sections.about) && (
              <a href="#about" className="hover:text-white transition-colors">About</a>
            )}
            {sections.skills && (
              <a href="#skills" className="hover:text-white transition-colors">Skills</a>
            )}
            {sections.projects && (
              <a href="#projects" className="hover:text-white transition-colors">Projects</a>
            )}
            {sections.blog && (
              <a href="#blog" className="hover:text-white transition-colors">Blog</a>
            )}
            {sections.contact && (
              <a href="#contact" className="hover:text-white transition-colors">Contact</a>
            )}
          </nav>

          {sections.contact && (
            <a
              href="#contact"
              className="text-sm font-semibold px-4 py-2 rounded-full transition-transform hover:-translate-y-px"
              style={{ backgroundColor: primary, color: '#0b1020' }}
            >
              Hire me
            </a>
          )}
        </div>
      </header>

      {/* Hero / About */}
      {(sections.hero || sections.about) && (
        <section className="px-5 pt-20 pb-14" id="about">
          <div className="max-w-5xl mx-auto bg-white/[0.04] border border-white/[0.08] rounded-2xl p-7 shadow-2xl grid grid-cols-[110px_1fr] gap-6 items-center">

            {/* Avatar */}
            <div className="w-[110px] h-[110px] rounded-full overflow-hidden border border-white/10 bg-white/5 flex items-center justify-center shrink-0">
              {avatarUrl ? (
                // eslint-disable-next-line @next/next/no-img-element
                <img src={avatarUrl} alt={`${tenant.name} avatar`} className="w-full h-full object-cover" />
              ) : (
                <span className="text-2xl font-extrabold text-slate-200 tracking-tight">
                  {initials(tenant.name)}
                </span>
              )}
            </div>

            {/* Text */}
            <div className="min-w-0">
              <h1
                className="text-5xl font-extrabold tracking-tight leading-tight mb-3"
                style={{ color: primary }}
              >
                {tenant.name}
              </h1>
              <p className="text-slate-400 text-base leading-relaxed max-w-2xl">
                {tenant.bio}
              </p>
              <div className="flex flex-wrap gap-3 mt-5">
                {sections.contact && (
                  <a
                    href="#contact"
                    className="inline-flex items-center px-5 py-2.5 rounded-full text-sm font-semibold transition-transform hover:-translate-y-px"
                    style={{ backgroundColor: primary, color: '#0b1020' }}
                  >
                    Let&apos;s connect
                  </a>
                )}
                {sections.skills && (
                  <a
                    href="#skills"
                    className="inline-flex items-center px-5 py-2.5 rounded-full text-sm font-semibold text-slate-200 border border-white/10 bg-white/5 hover:border-white/20 transition-all hover:-translate-y-px"
                  >
                    View skills
                  </a>
                )}
              </div>
            </div>
          </div>
        </section>
      )}

      {/* Skills */}
      {sections.skills && (
        <section className="px-5 py-14 max-w-5xl mx-auto" id="skills">
          <h2 className="text-2xl font-bold text-center tracking-tight mb-7">Skills</h2>
          <div className="flex flex-wrap gap-3 justify-center">
            {tenant.skills.map((skill: string) => (
              <span
                key={skill}
                className="px-4 py-2 rounded-full text-sm font-semibold bg-white/5 backdrop-blur-sm hover:-translate-y-0.5 hover:shadow-lg transition-all"
                style={{ border: `1px solid ${primary}` }}
              >
                {skill}
              </span>
            ))}
          </div>
        </section>
      )}

      {/* Projects */}
      {sections.projects && (
        <section className="px-5 py-14 max-w-5xl mx-auto" id="projects">
          <h2 className="text-2xl font-bold text-center tracking-tight mb-7">Projects</h2>
          <div className="flex flex-wrap gap-3 justify-center">
            {['Portfolio SaaS', 'Multi-tenant Routing', 'Template Builder'].map((p) => (
              <span
                key={p}
                className="px-4 py-2 rounded-full text-sm font-semibold bg-white/5 backdrop-blur-sm hover:-translate-y-0.5 hover:shadow-lg transition-all"
                style={{ border: `1px solid ${primary}` }}
              >
                {p}
              </span>
            ))}
          </div>
        </section>
      )}

      {/* Blog */}
      {sections.blog && (
        <section className="px-5 py-14 max-w-5xl mx-auto" id="blog">
          <h2 className="text-2xl font-bold text-center tracking-tight mb-7">Blog</h2>
          <div className="flex flex-wrap gap-3 justify-center">
            {[
              'How I built this portfolio',
              'Next.js Middleware Tips',
              'Designing Templates',
            ].map((post) => (
              <span
                key={post}
                className="px-4 py-2 rounded-full text-sm font-semibold bg-white/5 backdrop-blur-sm hover:-translate-y-0.5 hover:shadow-lg transition-all"
                style={{ border: `1px solid ${primary}` }}
              >
                {post}
              </span>
            ))}
          </div>
        </section>
      )}

      {/* Contact */}
      {sections.contact && (
        <section className="px-5 pt-2 pb-16" id="contact">
          <div className="max-w-3xl mx-auto bg-white/[0.04] border border-white/[0.08] rounded-2xl p-7">
            <h2 className="text-xl font-bold mb-2">Contact</h2>
            <p className="text-slate-400 leading-relaxed mb-5">
              Want to work together? Send a message and I&apos;ll reply quickly.
            </p>
            <div className="flex flex-wrap gap-3">
              <a
                href={`mailto:hello@${tenant.slug}.com`}
                className="inline-flex items-center px-5 py-2.5 rounded-full text-sm font-semibold transition-transform hover:-translate-y-px"
                style={{ backgroundColor: primary, color: '#0b1020' }}
              >
                Email me
              </a>
              <a
                href="#about"
                className="inline-flex items-center px-5 py-2.5 rounded-full text-sm font-semibold text-slate-200 border border-white/10 bg-white/5 hover:border-white/20 transition-all hover:-translate-y-px"
              >
                Back to top
              </a>
            </div>
          </div>
        </section>
      )}

      {/* Footer */}
      <footer className="text-center text-xs text-slate-500 py-5 border-t border-white/5">
        © {new Date().getFullYear()} {tenant.name}
      </footer>
    </div>
  );
}

There are a few important details in this page worth calling out.

The generateMetadata function runs server-side before the page renders and sets the page title, description, and Open Graph tags for each tenant individually. This means every portfolio gets its own SEO metadata — important for a real SaaS product.

The sections object merges safe defaults (hero: true, skills: true, and so on) with whatever the tenant's template specifies. This means even if the template JSON is missing a key, the page won't break — the section will simply fall back to being shown.

The initials helper generates a two-letter avatar placeholder from the tenant's name when no profile image is available. "Jane Smith" produces "JS" — a small detail that makes the portfolio look polished even before a user adds a photo.

Notice that the primary color from the template JSON (theme.primaryColor) is applied using the style prop rather than a Tailwind class. This is intentional. Tailwind generates class names at build time and cannot know the dynamic color value stored in your database. Inline styles are the correct approach whenever a CSS value is truly dynamic.

How to Test the Full Flow

Start both servers in separate terminal windows:

# Terminal 1 — Backend
cd portfolio-api
npm run dev

# Terminal 2 — Frontend
cd portfolio-client
npm run dev

Now test the complete flow:

1. Visit http://localhost:3000 and fill out the form with your name, a short bio, and a comma-separated list of skills.

2. Click Create Portfolio. The form submits to your Express API, which creates the tenant record and returns the slug.

3. Your browser redirects to http://your-name.localhost:3000.

4. The Next.js middleware detects the subdomain, rewrites the request to /tenant/your-name, and your portfolio page fetches and renders your data.

You should see a fully rendered portfolio page with your name, bio, skills, and the placeholder projects and blog sections — all styled with Tailwind utility classes.

Next Steps

You now have a working multi-tenant SaaS foundation. Here are some extensions worth considering for a production build:

You could add authentication with NextAuth.js so tenants can log in and update their portfolio without losing their data between sessions.

You could also add custom domain support so tenants can point their own domain (for example, janedoe.com) to their portfolio by adding a CNAME record. You would need to handle wildcard SSL certificates on your hosting provider.

You could add image uploads for avatars using Cloudinary or AWS S3, then store the URL in the tenant record and replace the initials fallback with a real photo.

You could add real blog post management using the Post model already defined in your schema. Tenants could write and publish posts that appear on their portfolio.

And you could add Stripe subscriptions so tenants pay a monthly fee to keep their portfolio live. The architecture from the Stripe Connect tutorial maps directly onto this.

Finally, you could deploy the backend to Railway or Render and the frontend to Vercel. Just make sure to update your API URLs from localhost:8080 to your production URL before deploying.

Conclusion

In this tutorial, you built a complete multi-tenant SaaS platform where users can sign up, get their own subdomain, and have a portfolio site generated instantly — all from a single codebase.

You learned how to use Next.js middleware to detect subdomains and rewrite requests dynamically, model multi-tenant data in Prisma with a slug-based routing system, build a JSON-driven template system that controls page layout without code changes, and style a production-ready Next.js frontend entirely with Tailwind CSS utility classes.

The core insight is that multi-tenancy isn't magic. It's subdomain detection plus dynamic routing plus isolated data. Once you understand those three moving parts, you can apply this pattern to any SaaS product you build.

If you found this tutorial helpful, share it with someone who is learning to build full-stack applications. Happy coding!

Source Code

You can find the complete source code for both parts of this project on GitHub:

• Frontend (Next.js multi-tenant app) + Backend (Express + Prisma API): https://github.com/michaelokolo/portfolio-saas-v1

Lazy loading helps solve this problem by splitting your code into smaller chunks and loading them only when they are needed

This guide walks you through lazy loading in React and Next.js. By the end, you'll know when to use React.lazy, next/dynamic, and Suspense, and you'll have working examples you can copy and adapt to your own projects.

Table of Contents

• What is Lazy Loading?

• Prerequisites

• How to Use React.lazy for Code Splitting

• How to Use Suspense with React.lazy

• How to Handle Errors with Error Boundaries

• How to Use next/dynamic in Next.js

• React.lazy vs next/dynamic: When to Use Each

• Real-World Examples

• Conclusion

What is Lazy Loading?

Lazy loading is a performance technique that defers loading code until it's needed. Instead of loading your entire app at once, you split it into smaller chunks. The browser only downloads a chunk when the user navigates to that route or interacts with that feature.

Benefits include:

• Faster initial load: Smaller first bundle means quicker time to interactive

• Better Core Web Vitals: Improves Largest Contentful Paint and Total Blocking Time

• Lower bandwidth: Users only download what they use

In React, you achieve this with dynamic imports and React.lazy() or Next.js’s next/dynamic.

Prerequisites

Before you follow along, you should have:

• Basic familiarity with React (components, hooks, state)

• Node.js installed (version 18 or later recommended)

• A React app (Create React App or Vite) or a Next.js app (for the Next.js examples)

For the React examples, you can use Create React App or Vite. For the Next.js examples, use the App Router (Next.js 13 or later).

How to Use React.lazy for Code Splitting

React.lazy() lets you define a component as a dynamic import. React will load that component only when it's first rendered.

React.lazy() expects a function that returns a dynamic import(). The imported module must use a default export.

Here's a basic example:

import { lazy } from 'react';

const HeavyChart = lazy(() => import('./HeavyChart'));
const AdminDashboard = lazy(() => import('./AdminDashboard'));

function App() {
  return (
    <div>
      <h1>My App</h1>
      <HeavyChart />
      <AdminDashboard />
    </div>
  );
}

If you use named exports, you can map them to a default export:

const ComponentWithNamedExport = lazy(() =>
  import('./MyComponent').then((module) => ({
    default: module.NamedComponent,
  }))
);

You can also name chunks for easier debugging in the browser:

const HeavyChart = lazy(() =>
  import(/* webpackChunkName: "heavy-chart" */ './HeavyChart')
);

React.lazy() alone isn't enough. You must wrap lazy components in Suspense so React knows what to show while they load.

How to Use Suspense with React.lazy

Suspense is a React component that shows a fallback UI while its children are loading. It works with React.lazy() to handle the loading state of dynamically imported components.

Wrap your lazy components in Suspense and provide a fallback prop:

import { lazy, Suspense } from 'react';

const HeavyChart = lazy(() => import('./HeavyChart'));
const AdminDashboard = lazy(() => import('./AdminDashboard'));

function App() {
  return (
    <div>
      <h1>My App</h1>
      <Suspense fallback={<div>Loading chart...</div>}>
        <HeavyChart />
      </Suspense>
      <Suspense fallback={<div>Loading dashboard...</div>}>
        <AdminDashboard />
      </Suspense>
    </div>
  );
}

You can use a single Suspense boundary for multiple lazy components:

<Suspense fallback={<div>Loading...</div>}>
  <HeavyChart />
  <AdminDashboard />
</Suspense>

A more polished fallback improves perceived performance:

function LoadingSpinner() {
  return (
    <div className="loading-container">
      <div className="spinner" />
      <p>Loading...</p>
    </div>
  );
}

<Suspense fallback={<LoadingSpinner />}>
  <HeavyChart />
</Suspense>

How to Handle Errors with Error Boundaries

React.lazy() and Suspense don't handle loading errors (for example, network failures or missing chunks). For that, you need an Error Boundary.

Error Boundaries are class components that use componentDidCatch or static getDerivedStateFromError to catch errors in their child tree and render a fallback UI.

Here is a simple Error Boundary:

import { Component } from 'react';

class ErrorBoundary extends Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    console.error('Error caught by boundary:', error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback || <div>Something went wrong.</div>;
    }
    return this.props.children;
  }
}

Wrap your Suspense boundary with an Error Boundary:

import { lazy, Suspense } from 'react';
import ErrorBoundary from './ErrorBoundary';

const HeavyChart = lazy(() => import('./HeavyChart'));

function App() {
  return (
    <ErrorBoundary fallback={<div>Failed to load chart. Please try again.</div>}>
      <Suspense fallback={<div>Loading chart...</div>}>
        <HeavyChart />
      </Suspense>
    </ErrorBoundary>
  );
}

If the chunk fails to load, the Error Boundary catches it and shows your fallback instead of a blank screen or unhandled error.

How to Use next/dynamic in Next.js

Next.js provides next/dynamic, which wraps React.lazy() and Suspense and adds options tailored for Next.js (including Server-Side Rendering).

Basic usage:

'use client';

import dynamic from 'next/dynamic';

const ComponentA = dynamic(() => import('../components/A'));
const ComponentB = dynamic(() => import('../components/B'));

export default function Page() {
  return (
    <div>
      <ComponentA />
      <ComponentB />
    </div>
  );
}

Custom Loading UI

Use the loading option to show a placeholder while the component loads:

const HeavyChart = dynamic(() => import('../components/HeavyChart'), {
  loading: () => <p>Loading chart...</p>,
});

Disable Server-Side Rendering

For components that must run only on the client (for example, those using window or browser-only APIs), set ssr: false:

const ClientOnlyMap = dynamic(() => import('../components/Map'), {
  ssr: false,
  loading: () => <p>Loading map...</p>,
});

Note: ssr: false works only for Client Components. Use it inside a 'use client' file.

Load on Demand

You can load a component only when a condition is met:

'use client';

import { useState } from 'react';
import dynamic from 'next/dynamic';

const Modal = dynamic(() => import('../components/Modal'), {
  loading: () => <p>Opening modal...</p>,
});

export default function Page() {
  const [showModal, setShowModal] = useState(false);

  return (
    <div>
      <button onClick={() => setShowModal(true)}>Open Modal</button>
      {showModal && <Modal onClose={() => setShowModal(false)} />}
    </div>
  );
}

Named Exports

For named exports, return the component from the dynamic import:

const Hello = dynamic(() =>
  import('../components/hello').then((mod) => mod.Hello)
);

Using Suspense with next/dynamic

In React 18+, you can use suspense: true to rely on a parent Suspense boundary instead of the loading option:

const HeavyChart = dynamic(() => import('../components/HeavyChart'), {
  suspense: true,
});

// In your component:
<Suspense fallback={<div>Loading...</div>}>
  <HeavyChart />
</Suspense>

Important: When using suspense: true, you can't use ssr: false or the loading option. Use the Suspense fallback instead.

React.lazy vs next/dynamic: When to Use Each

When to Use React.lazy

• You're building a pure React app (no Next.js)

• You use Create React App, Vite, or a custom Webpack setup

• You don't need Server-Side Rendering

• You want a simple, framework-agnostic approach

When to Use next/dynamic

• You're building a Next.js app

• You need SSR for some components and want to disable it for others

• You want built-in loading placeholders without manually adding Suspense

• You want Next.js-specific optimizations and defaults

Real-World Examples

Example 1: Route-Based Code Splitting in React

Split your app by route so each page loads only when the user navigates to it:

// App.jsx
import { lazy, Suspense } from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import ErrorBoundary from './ErrorBoundary';

const Home = lazy(() => import('./pages/Home'));
const Dashboard = lazy(() => import('./pages/Dashboard'));
const Settings = lazy(() => import('./pages/Settings'));

function App() {
  return (
    <BrowserRouter>
      <ErrorBoundary fallback={<div>Failed to load page.</div>}>
        <Suspense fallback={<div>Loading page...</div>}>
          <Routes>
            <Route path="/" element={<Home />} />
            <Route path="/dashboard" element={<Dashboard />} />
            <Route path="/settings" element={<Settings />} />
          </Routes>
        </Suspense>
      </ErrorBoundary>
    </BrowserRouter>
  );
}

Example 2: Lazy Loading a Heavy Chart Library in Next.js

Defer loading a chart library until the user opens the analytics section:

// app/analytics/page.jsx
'use client';

import { useState } from 'react';
import dynamic from 'next/dynamic';

const Chart = dynamic(() => import('../components/Chart'), {
  ssr: false,
  loading: () => (
    <div className="chart-skeleton">
      <div className="skeleton-bar" />
      <div className="skeleton-bar" />
      <div className="skeleton-bar" />
    </div>
  ),
});

export default function AnalyticsPage() {
  const [showChart, setShowChart] = useState(false);

  return (
    <div>
      <h1>Analytics</h1>
      <button onClick={() => setShowChart(true)}>Load Chart</button>
      {showChart && <Chart />}
    </div>
  );
}

Example 3: Lazy Loading a Modal

Load a modal component only when the user clicks to open it:

// React (with React.lazy)
import { lazy, Suspense, useState } from 'react';

const Modal = lazy(() => import('./Modal'));

function ProductPage() {
  const [showModal, setShowModal] = useState(false);

  return (
    <div>
      <button onClick={() => setShowModal(true)}>Add to Cart</button>
      {showModal && (
        <Suspense fallback={null}>
          <Modal onClose={() => setShowModal(false)} />
        </Suspense>
      )}
    </div>
  );
}

// Next.js (with next/dynamic)
'use client';

import { useState } from 'react';
import dynamic from 'next/dynamic';

const Modal = dynamic(() => import('./Modal'), {
  loading: () => null,
});

export default function ProductPage() {
  const [showModal, setShowModal] = useState(false);

  return (
    <div>
      <button onClick={() => setShowModal(true)}>Add to Cart</button>
      {showModal && <Modal onClose={() => setShowModal(false)} />}
    </div>
  );
}

Example 4: Lazy Loading External Libraries

Load a library only when the user needs it (for example, when they start typing in a search box):

'use client';

import { useState } from 'react';

const names = ['Alice', 'Bob', 'Charlie', 'Diana'];

export default function SearchPage() {
  const [results, setResults] = useState([]);
  const [query, setQuery] = useState('');

  const handleSearch = async (value) => {
    setQuery(value);
    if (!value) {
      setResults([]);
      return;
    }
    // Load fuse.js only when user searches
    const Fuse = (await import('fuse.js')).default;
    const fuse = new Fuse(names);
    setResults(fuse.search(value));
  };

  return (
    <div>
      <input
        type="text"
        placeholder="Search..."
        value={query}
        onChange={(e) => handleSearch(e.target.value)}
      />
      <ul>
        {results.map((result) => (
          <li key={result.refIndex}>{result.item}</li>
        ))}
      </ul>
    </div>
  );
}

Conclusion

Lazy loading improves performance by splitting your bundle and loading code only when needed. Here's what you learned:

• React.lazy() – Use in plain React apps for code splitting. It requires a default export and works with dynamic import().

• Suspense – Wrap lazy components in Suspense and provide a fallback for the loading state.

• Error Boundaries – Use them to catch chunk load failures and show a friendly error UI.

• next/dynamic – Use in Next.js for the same benefits plus SSR control and built-in loading options.

Choose React.lazy for React-only projects and next/dynamic for Next.js. Combine them with Suspense and Error Boundaries for a solid lazy-loading setup.

Start by identifying your heaviest components (charts, modals, admin panels) and lazy load them. Measure your bundle size and Core Web Vitals before and after to see the impact.

In this handbook, you'll build a complete marketplace from scratch using TypeScript. You won't need a traditional database. Instead, you'll use Stripe as your product catalog and payment engine.

This is how many real-world marketplaces work: Stripe stores the products, prices, and customer data, while your application handles the user experience.

Here's what you'll build:

1. A merchant onboarding flow where sellers create accounts and connect with Stripe

2. A product management system where merchants can add and list products directly through Stripe

3. A checkout flow that supports both one-time payments and recurring subscriptions

4. Webhooks that listen for payment events in real time

5. A billing portal where customers can manage their subscriptions

6. A complete storefront where customers can browse and buy products

You can also grab the complete source code from the GitHub repository linked at the end.

Table of Contents

• Prerequisites

• What is Stripe Connect?

• How to Set Up the Project

• How to Set Up the Backend

• How to Build the Express Backend

• How to Handle Merchant Onboarding

  • How to Create a Connected Account

  • How to Create the Onboarding Link

• How to Check Account Status

• How to Create Products Through Stripe

• How to Fetch Products

• How to Build the Checkout Flow

• How to Handle Webhooks

• How to Configure Webhooks in the Stripe Dashboard

• How to Test Webhooks Locally

• How to Add the Billing Portal

• How to Build the Next.js Frontend

• How to Create the Account Context

• How to Create the Account Status Hook

• How to Build the Merchant Onboarding Component

• How to Build the Product Create, Product List and Checkout

• How to Build the Product Form

• How to Build the Main Page

• How to Test the Full Flow

• How the Payment Split Works

• Next Steps

• Acknowledgements

• Conclusion

Prerequisites

Before you begin, make sure you have the following:

1. Node.js (version 18 or higher) installed on your machine

2. A basic understanding of React, TypeScript, and REST APIs

3. A Stripe account (sign up for free at stripe.com)

4. A code editor like VS Code

You do not need a database for this project. Stripe will store your products, prices, and customer information. This keeps the architecture simple and mirrors how many production marketplaces actually work.

What is Stripe Connect?

Stripe Connect is a set of APIs designed for platforms and marketplaces. It lets you create accounts for your merchants (Stripe calls them "connected accounts"), route payments to them, and take a platform fee on every transaction.

In this tutorial, you will use Stripe’s V2 Accounts API, which is the newer and recommended way to create connected accounts. With the V2 API, you configure what each account can do (accept card payments, receive payouts) through a configuration object, and Stripe handles all compliance and identity verification through a hosted onboarding flow.

Here's how the payment flow works:

1. A customer selects a product and clicks checkout on your marketplace.

2. Your server creates a Stripe Checkout Session linked to the merchant’s connected account.

3. The customer pays on Stripe’s hosted checkout page.

4. Stripe automatically splits the payment: the merchant gets their share, and your platform keeps an application fee.

5. Stripe sends a webhook event to your server confirming the payment.

6. The merchant can view their earnings and withdraw funds from their Stripe dashboard.

How to Set Up the Project

Create a project folder with separate directories for your backend and frontend:

mkdir marketplace && cd marketplace
mkdir server client

How to Set Up the Backend

Navigate into the server directory and initialize a TypeScript project:

cd server
npm init -y
npm install express cors dotenv stripe
npm install -D typescript ts-node @types/express @types/cors @types/node
npx tsc --init
mkdir src

Open tsconfig.json and update it with these settings:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"]
}

Then create a .env file in the server root:

STRIPE_SECRET_KEY=sk_test_your_key_here
DOMAIN=http://localhost:3000

You can find your Stripe test secret key in the Stripe Dashboard under Developers > API Keys. The DOMAIN variable tells your server where to redirect customers after checkout.

Add these scripts to your package.json:

{
  "scripts": {
    "dev": "ts-node src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

How to Build the Express Backend

Create the file src/index.ts. This will be your entire backend. Let’s start with the setup and imports:

import express, { Request, Response, Router } from 'express';
import cors from 'cors';
import dotenv from 'dotenv';
import Stripe from 'stripe';

dotenv.config();

const app = express();
const router = Router();
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string);

app.use(cors({ origin: process.env.DOMAIN }));
app.use(express.static('public'));

Notice that we don't import any database client. Stripe is our data layer. Every product, price, customer, and transaction lives in Stripe. Your Express server is a thin orchestration layer that talks to the Stripe API on behalf of your frontend.

We also mount express.static("public") so you can serve static files later if needed. The webhook endpoint needs the raw request body, so we'll register it before the JSON parser. Let’s add that now.

How to Handle Merchant Onboarding

The first thing a merchant needs to do is create an account on your platform and connect it to Stripe. This involves two steps: creating a connected account, and then redirecting the merchant to Stripe’s hosted onboarding form.

How to Create a Connected Account

Add the following route to your src/index.ts:

// Type definitions for request bodies
interface CreateAccountBody {
  email: string;
}
interface AccountIdBody {
  accountId: string;
}

// Create a Connected Account using Stripe V2 API
router.post(
  '/create-connect-account',
  async (req: Request<{}, {}, CreateAccountBody>, res: Response) => {
    try {
      const account = await stripe.v2.core.accounts.create({
        display_name: req.body.email,
        contact_email: req.body.email,
        dashboard: 'full',
        defaults: {
          responsibilities: {
            fees_collector: 'stripe',
            losses_collector: 'stripe',
          },
        },
        identity: {
          country: 'GB',
          entity_type: 'company',
        },
        configuration: {
          customer: {},
          merchant: {
            capabilities: {
              card_payments: { requested: true },
            },
          },
        },
      });
      res.json({ accountId: account.id });
    } catch (error) {
      const message = error instanceof Error ? error.message : 'Unknown error';
      res.status(500).json({ error: message });
    }
  },
);

Let’s break down what this code does. The stripe.v2.core.accounts.create() method creates a new connected account using Stripe’s V2 API. Here are the key configuration options:

1. dashboard: "full" gives the merchant access to their own Stripe dashboard where they can view payments, manage payouts, and handle disputes.

2. responsibilities tells Stripe who collects fees and who is liable for losses. Setting both to "stripe" means Stripe handles this, which is the simplest configuration.

3. identity sets the country and entity type. Change "GB" to your merchants’ country code (for example, "US" for the United States).

4. configuration.merchant.capabilities requests the card_payments capability, which lets the merchant accept credit card payments.

How to Create the Onboarding Link

After creating the account, you need to redirect the merchant to Stripe’s hosted onboarding form. Add this route:

// Create Account Link for onboarding
router.post('/create-account-link', async (req: Request<{}, {}, AccountIdBody>, res: Response) => {
  const { accountId } = req.body;
  try {
    const accountLink = await stripe.v2.core.accountLinks.create({
      account: accountId,
      use_case: {
        type: 'account_onboarding',
        account_onboarding: {
          configurations: ['merchant', 'customer'],
          refresh_url: `${process.env.DOMAIN}`,
          return_url: `\({process.env.DOMAIN}?accountId=\){accountId}`,
        },
      },
    });
    res.json({ url: accountLink.url });
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Unknown error';
    res.status(500).json({ error: message });
  }
});

The accountLinks.create() method generates a temporary URL that takes the merchant to Stripe’s onboarding form. On that form, Stripe collects the merchant’s identity documents, bank account details, and tax information. You don't need to build any of this yourself.

The return_url is where Stripe redirects the merchant after they complete onboarding. Notice that you append the accountId as a query parameter so your frontend can pick it up and store it.

How to Check Account Status

You need a way to check whether a merchant has finished onboarding and is ready to accept payments. Add this route:

// Get Connected Account Status
router.get(
  '/account-status/:accountId',
  async (req: Request<{ accountId: string }>, res: Response) => {
    try {
      const account = await stripe.v2.core.accounts.retrieve(req.params.accountId, {
        include: ['requirements', 'configuration.merchant'],
      });
      const payoutsEnabled =
        account.configuration?.merchant?.capabilities?.stripe_balance?.payouts?.status === 'active';
      const chargesEnabled =
        account.configuration?.merchant?.capabilities?.card_payments?.status === 'active';
      const summaryStatus = account.requirements?.summary?.minimum_deadline?.status;
      const detailsSubmitted = !summaryStatus || summaryStatus === 'eventually_due';
      res.json({
        id: account.id,
        payoutsEnabled,
        chargesEnabled,
        detailsSubmitted,
        requirements: account.requirements?.entries,
      });
    } catch (error) {
      const message = error instanceof Error ? error.message : 'Unknown error';
      res.status(500).json({ error: message });
    }
  },
);

This route retrieves the connected account and checks three important statuses:

• chargesEnabled tells you if the merchant can accept payments.

• payoutsEnabled tells you if they can receive payouts to their bank account.

• detailsSubmitted tells you if they have completed the onboarding form.

Your frontend will use these flags to show or hide features.

How to Create Products Through Stripe

Instead of storing products in a database, you'll create them directly in Stripe. Each product is created on the merchant’s connected account using the stripeAccount header. This means each merchant has their own isolated product catalog inside Stripe.

// Type definition for product creation
interface CreateProductBody {
  productName: string;
  productDescription: string;
  productPrice: number;
  accountId: string;
}
// Create a product on the connected account
router.post('/create-product', async (req: Request<{}, {}, CreateProductBody>, res: Response) => {
  const { productName, productDescription, productPrice, accountId } = req.body;
  try {
    // Create the product on the connected account
    const product = await stripe.products.create(
      {
        name: productName,
        description: productDescription,
      },
      { stripeAccount: accountId },
    ); // Create a price for the product
    const price = await stripe.prices.create(
      {
        product: product.id,
        unit_amount: productPrice,
        currency: 'usd',
      },
      { stripeAccount: accountId },
    );
    res.json({
      productName,
      productDescription,
      productPrice,
      priceId: price.id,
    });
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Unknown error';
    res.status(500).json({ error: message });
  }
});

There are two Stripe API calls happening here. First, stripe.products.create() creates the product (name and description). Then stripe.prices.create() creates a price for that product (amount and currency).

Stripe separates products from prices because a single product can have multiple prices — for example, a monthly plan and an annual plan.

The { stripeAccount: accountId } option on both calls tells Stripe to create these resources on the merchant’s connected account, not on your platform account. This is a critical detail: without it, the products would be created on your platform’s account and the merchant would never see them.

How to Fetch Products

Add a route to list all products for a given merchant:

// Fetch products for a specific account
router.get('/products/:accountId', async (req: Request<{ accountId: string }>, res: Response) => {
  const { accountId } = req.params;
  try {
    const options: Stripe.RequestOptions = {};
    if (accountId !== 'platform') {
      options.stripeAccount = accountId;
    }
    const prices = await stripe.prices.list(
      {
        expand: ['data.product'],
        active: true,
        limit: 100,
      },
      options,
    );
    const products = prices.data.map((price) => {
      const product = price.product as Stripe.Product;
      return {
        id: product.id,
        name: product.name,
        description: product.description,
        price: price.unit_amount,
        priceId: price.id,
        period: price.recurring ? price.recurring.interval : null,
      };
    });
    res.json(products);
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Unknown error';
    res.status(500).json({ error: message });
  }
});

This route fetches all active prices from a merchant’s Stripe account and expands the product data (using expand: ["data.product"]) so you get the product name and description in the same API call. The period field will be null for one-time products and "month" or "year" for subscriptions.

How to Build the Checkout Flow

Your checkout flow needs to handle two scenarios: one-time payments for individual products, and recurring subscriptions. Stripe’s Checkout Sessions handle both — you just need to set the mode based on the price type.

// Type definition for checkout
interface CheckoutBody {
  priceId: string;
  accountId: string;
}
// Create checkout session
router.post(
  '/create-checkout-session',
  async (req: Request<{}, {}, CheckoutBody>, res: Response) => {
    const { priceId, accountId } = req.body;
    try {
      // Retrieve the price to determine if it is
      // one-time or recurring
      const price = await stripe.prices.retrieve(priceId, { stripeAccount: accountId });
      const isSubscription = price.type === 'recurring';
      const mode = isSubscription ? 'subscription' : 'payment';
      const session = await stripe.checkout.sessions.create(
        {
          line_items: [
            {
              price: priceId,
              quantity: 1,
            },
          ],
          mode,
          success_url: `${process.env.DOMAIN}/done?session_id={CHECKOUT_SESSION_ID}`,
          cancel_url: `${process.env.DOMAIN}`,
          ...(isSubscription
            ? {
                subscription_data: {
                  application_fee_percent: 10,
                },
              }
            : {
                payment_intent_data: {
                  application_fee_amount: 123,
                },
              }),
        },
        { stripeAccount: accountId },
      );
      res.redirect(303, session.url as string);
    } catch (error) {
      const message = error instanceof Error ? error.message : 'Unknown error';
      res.status(500).json({ error: message });
    }
  },
);

Here's what this route does step by step. First, it retrieves the price from the merchant’s connected account to check whether it is a one-time price or a recurring subscription. Then it creates a Checkout Session with the appropriate mode — either "payment" or "subscription".

The application_fee_amount is your platform’s cut of the transaction, specified in the smallest currency unit (cents for USD). In this example, you take $1.23 or 10% per transaction. For a real marketplace, you would likely calculate this as a percentage of the product price.

Notice that application_fee_amount goes inside subscription_data for subscriptions but inside payment_intent_data for one-time payments. This is a Stripe requirement — the two modes use different configuration objects.

Finally, the route uses res.redirect(303, session.url) to send the customer directly to Stripe’s hosted checkout page.

How to Handle Webhooks

Webhooks are how Stripe tells your server about events that happen asynchronously — like a successful payment, a failed charge, or a subscription cancellation.

In a production marketplace, you should never rely solely on redirect URLs to confirm payments. A customer might close their browser before the redirect completes. Webhooks are your source of truth.

Add the webhook endpoint before the JSON body parser. Stripe sends webhook payloads as raw bytes, and you need the raw body to verify the signature:

// IMPORTANT: Register this BEFORE app.use(express.json())
app.post(
  '/api/webhook',
  express.raw({ type: 'application/json' }),
  (req: Request, res: Response) => {
    let event: Stripe.Event = JSON.parse(req.body.toString()); // If you have an endpoint secret, verify the
    // signature for security
    const endpointSecret = process.env.WEBHOOK_SECRET;
    if (endpointSecret) {
      const signature = req.headers['stripe-signature'] as string;
      try {
        event = stripe.webhooks.constructEvent(req.body, signature, endpointSecret) as Stripe.Event;
      } catch (err) {
        const message = err instanceof Error ? err.message : 'Unknown error';
        console.log('Webhook signature verification failed:', message);
        res.sendStatus(400);
        return;
      }
    } // Handle the event
    switch (event.type) {
      case 'checkout.session.completed': {
        const session = event.data.object as Stripe.Checkout.Session;
        console.log('Payment successful for session:', session.id); // Fulfill the order: send email, grant access,
        // update your records, and so on
        break;
      }
      case 'checkout.session.expired': {
        const session = event.data.object as Stripe.Checkout.Session;
        console.log('Session expired:', session.id); // Optionally notify the customer or clean up
        // any pending records
        break;
      }
      case 'checkout.session.async_payment_succeeded': {
        const session = event.data.object as Stripe.Checkout.Session;
        console.log('Delayed payment succeeded for session:', session.id); // Fulfill the order now that payment cleared
        break;
      }
      case 'checkout.session.async_payment_failed': {
        const session = event.data.object as Stripe.Checkout.Session;
        console.log('Payment failed for session:', session.id); // Notify the customer that payment failed
        break;
      }
      case 'customer.subscription.deleted': {
        const subscription = event.data.object as Stripe.Subscription;
        console.log('Subscription cancelled:', subscription.id); // Revoke access for the customer
        break;
      }
      default:
        console.log('Unhandled event type:', event.type);
    }
    res.send();
  },
);

The webhook handler checks for five key events.

• checkout.session.completed fires when a payment succeeds — this is where you would fulfill an order, send a confirmation email, or grant access.

• checkout.session.expired fires when a session expires before the customer completes payment.

• checkout.session.async_payment_succeeded fires when a delayed payment method (like a bank transfer) finally goes through.

• checkout.session.async_payment_failed fires when a delayed payment method fails.

• And customer.subscription.deleted fires when a subscription is cancelled.

How to Configure Webhooks in the Stripe Dashboard

Before you can receive webhook events, you need to tell Stripe where to send them and which events you care about. Follow these steps:

1. Go to the Stripe Dashboard and navigate to Developers > Webhooks.

2. Click "Add destination."

3. Under the account type, select "Connected and V2 accounts" since your payments go through connected merchant accounts.

4. Under "Events to listen for," click "All events" and select the following five events:

   • checkout.session.async_payment_succeeded — Occurs when a payment intent using a delayed payment method finally succeeds.

   • checkout.session.completed — Occurs when a Checkout Session has been successfully completed.

   • checkout.session.expired — Occurs when a Checkout Session expires before completion.

   • checkout.session.async_payment_failed — Occurs when a payment intent using a delayed payment method fails.

   • customer.subscription.deleted — Occurs whenever a customer’s subscription ends.

5. Enter your webhook endpoint URL. For production, this would be something like https://yourdomain.com/api/webhook. For local development, you will use the Stripe CLI instead (covered next).

6. Click "Add destination" to save.

How to Test Webhooks Locally

For local development, you don't need to expose your server to the internet. Install the Stripe CLI and run:

brew install stripe/stripe-cli/stripe
stripe login
stripe listen --forward-to localhost:4242/webhook

The CLI will print a webhook signing secret that starts with whsec_. Add this to your .env file as WEBHOOK_SECRET. The CLI intercepts all webhook events from Stripe and forwards them to your local server, so you can test the full payment flow without deploying anything.

How to Add the Billing Portal

The billing portal lets customers manage their subscriptions without you building any UI for it. Stripe hosts the entire experience — customers can update their payment method, change plans, or cancel their subscription.

// Create a billing portal session
router.post(
  "/create-portal-session",
  async (req: Request, res: Response) => {
    const { session_id } = req.body as {
      session_id: string;
    };
 
    try {
      const session =
        await stripe.checkout.sessions.retrieve(
          session_id
        );
 
      const portalSession =
        await stripe.billingPortal.sessions.create({
          customer_account: session.customer_account as string,
          return_url: `\({process.env.DOMAIN}?session_id=\){session_id}`,
        });
 
      res.redirect(303, portalSession.url);
    } catch (error) {
      const message =
        error instanceof Error
          ? error.message
          : "Unknown error";
      res.status(500).json({ error: message });
    }
  }
);

This route takes a session_id from a previous checkout, retrieves the associated customer, and creates a billing portal session. The customer_account field links the portal to the correct connected account so the customer sees only their subscriptions with that specific merchant.

Now add the JSON parser and mount the router. This must come after the webhook route:

// JSON and URL-encoded parsers (AFTER webhook route)
app.use(express.urlencoded({ extended: true }));
app.use(express.json());

// Mount all routes under /api
app.use('/api', router);
const PORT: number = parseInt(process.env.PORT || '4242', 10);
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

How to Build the Next.js Frontend

Navigate to the client directory and create a new Next.js project with TypeScript:

cd ../client
npx create-next-app@latest . --typescript --app --tailwind --eslint
npm install axios

How to Create the Account Context

You need a way to share the merchant’s account ID across all components. Create a context provider at contexts/AccountContext.tsx:

'use client';
import { createContext, useContext, useState, ReactNode } from 'react';
import { useSearchParams } from 'next/navigation';

interface AccountContextType {
  accountId: string | null;
  setAccountId: (id: string | null) => void;
}

const AccountContext = createContext<AccountContextType | undefined>(undefined);

export function useAccount(): AccountContextType {
  const context = useContext(AccountContext);
  if (!context) {
    throw new Error('useAccount must be used within AccountProvider');
  }
  return context;
}

export function AccountProvider({ children }: { children: ReactNode }) {
  const searchParams = useSearchParams();
  const [accountId, setAccountId] = useState<string | null>(searchParams.get('accountId'));

  return (
    <AccountContext.Provider value={{ accountId, setAccountId }}>
      {children}
    </AccountContext.Provider>
  );
}

This context stores the current merchant’s account ID and makes it available throughout the app. On initial load, it checks the URL for an accountId query parameter — this is how Stripe’s onboarding redirect passes the account ID back to your app.

How to Create the Account Status Hook

Create a custom hook at hooks/useAccountStatus.ts that polls the account status:

'use client';
import { useState, useEffect } from 'react';
import { useAccount } from '@/contexts/AccountContext';
interface AccountStatus {
  id: string;
  payoutsEnabled: boolean;
  chargesEnabled: boolean;
  detailsSubmitted: boolean;
}
export default function useAccountStatus() {
  const [accountStatus, setAccountStatus] = useState<AccountStatus | null>(null);
  const { accountId, setAccountId } = useAccount();
  useEffect(() => {
    if (!accountId) return;
    const fetchStatus = async () => {
      try {
        const res = await fetch(`http://localhost:4242/api/account-status/${accountId}`);
        if (!res.ok) throw new Error('Failed to fetch');
        const data: AccountStatus = await res.json();
        setAccountStatus(data);
      } catch {
        setAccountId(null);
      }
    };
    fetchStatus();
    const interval = setInterval(fetchStatus, 5000);
    return () => clearInterval(interval);
  }, [accountId, setAccountId]);
  return {
    accountStatus,
    needsOnboarding: !accountStatus?.chargesEnabled && !accountStatus?.detailsSubmitted,
  };
}

This hook polls the account status every 5 seconds. This is important because Stripe’s onboarding is asynchronous — a merchant might complete the form, but it can take a moment for Stripe to verify their details and activate their account. The needsOnboarding flag tells your UI whether to show the onboarding button or the merchant dashboard.

How to Build the Merchant Onboarding Component

Create components/ConnectOnboarding.tsx:

'use client';
import { useState } from 'react';
import { useAccount } from '@/contexts/AccountContext';
import useAccountStatus from '@/hooks/useAccountStatus';
const API_URL = 'http://localhost:4242/api';
export default function ConnectOnboarding() {
  const [email, setEmail] = useState<string>('');
  const { accountId, setAccountId } = useAccount();
  const { accountStatus, needsOnboarding } = useAccountStatus();
  const handleCreateAccount = async () => {
    const res = await fetch(`${API_URL}/create-connect-account`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email }),
    });
    const data = await res.json();
    setAccountId(data.accountId);
  };
  const handleStartOnboarding = async () => {
    const res = await fetch(`${API_URL}/create-account-link`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ accountId }),
    });
    const data = await res.json();
    window.location.href = data.url;
  };
  if (!accountId) {
    return (
      <div className="max-w-md mx-auto p-6">
        <h2 className="text-xl font-bold mb-4">Create Your Seller Account</h2>
        <input
          type="email"
          placeholder="Your email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          className="w-full border p-2 rounded mb-4"
        />
        <button
          onClick={handleCreateAccount}
          className="w-full bg-green-600 text-white p-2 rounded hover:bg-green-700"
        >
          Create Connect Account
        </button>
      </div>
    );
  }
  return (
    <div className="max-w-md mx-auto p-6">
      <h3 className="font-semibold mb-2">Account: {accountId} </h3>
      <p className="mb-2">Charges: {accountStatus?.chargesEnabled ? 'Active' : 'Pending'} </p>
      <p className="mb-4">Payouts: {accountStatus?.payoutsEnabled ? 'Active' : 'Pending'} </p>
      {needsOnboarding && (
        <button
          onClick={handleStartOnboarding}
          className="bg-purple-600 text-white px-6 py-2 rounded hover:bg-purple-700"
        >
          Complete Onboarding
        </button>
      )}
    </div>
  );
}

This component handles both states of the merchant experience. If no account exists, it shows a simple email form. After account creation, it shows the account status and an onboarding button if needed.

How to Build the Product Create, Product List and Checkout

Create components/Products.tsx:

'use client';
import { useState, useEffect } from 'react';
import { useAccount } from '@/contexts/AccountContext';
import useAccountStatus from '@/hooks/useAccountStatus';
const API_URL = 'http://localhost:4242/api';
interface Product {
  id: string;
  name: string;
  description: string | null;
  price: number | null;
  priceId: string;
  period: string | null;
}
export default function Products() {
  const { accountId } = useAccount();
  const { needsOnboarding } = useAccountStatus();
  const [products, setProducts] = useState<Product[]>([]);
  useEffect(() => {
    if (!accountId || needsOnboarding) return;
    const fetchProducts = async () => {
      const res = await fetch(`\({API_URL}/products/\){accountId}`);
      const data: Product[] = await res.json();
      setProducts(data);
    };
    fetchProducts();
    const interval = setInterval(fetchProducts, 5000);
    return () => clearInterval(interval);
  }, [accountId, needsOnboarding]);
  return (
    <div className="grid grid-cols-1 md:grid-cols-3 gap-6 mt-6">
      {' '}
      {products.map((product) => (
        <div key={product.priceId} className="border rounded-lg p-4 shadow-sm">
          <h3 className="text-lg font-semibold">  {product.name}</h3>

          <p className="text-gray-600 mt-1">  {product.description}</p>

          <p className="text-xl font-bold mt-3">
            ${((product.price ?? 0) / 100).toFixed(2)}
            {product.period ? ` / ${product.period}` : ''}
          </p>

          <form action={`${API_URL}/create-checkout-session`} method="POST">
            <input type="hidden" name="priceId" value={product.priceId} />
            <input type="hidden" name="accountId" value={accountId ?? ''} />
            <button
              type="submit"
              className="mt-4 w-full bg-blue-600 text-white py-2 rounded hover:bg-blue-700"
            >
              {product.period ? 'Subscribe' : 'Buy Now'}
            </button>
          </form>
        </div>
      ))}
    </div>
  );
}

The Products component fetches all products from the merchant’s Stripe account and displays them in a responsive grid. The checkout button submits a form directly to your backend, which redirects the customer to Stripe’s hosted checkout page. Notice how the button text changes based on whether the product is a one-time purchase or a subscription.

How to Build the Product Form

Merchants need a way to add products from the frontend. Create components/ProductForm.tsx:

'use client';
import { useState } from 'react';
import { useAccount } from '@/contexts/AccountContext';
import useAccountStatus from '@/hooks/useAccountStatus';
const API_URL = 'http://localhost:4242/api';
interface ProductFormData {
  productName: string;
  productDescription: string;
  productPrice: number;
}
export default function ProductForm() {
  const { accountId } = useAccount();
  const { needsOnboarding } = useAccountStatus();
  const [showForm, setShowForm] = useState<boolean>(false);
  const [formData, setFormData] = useState<ProductFormData>({
    productName: '',
    productDescription: '',
    productPrice: 1000,
  });
  const handleSubmit = async (e: React.FormEvent): Promise<void> => {
    e.preventDefault();
    if (!accountId || needsOnboarding) return;
    await fetch(`${API_URL}/create-product`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        ...formData,
        accountId,
      }),
    }); // Reset form and hide it
    setFormData({
      productName: '',
      productDescription: '',
      productPrice: 1000,
    });
    setShowForm(false);
  }; // Only show the form if the merchant has completed
  // onboarding and can accept charges
  if (!accountId || needsOnboarding) return null;
  return (
    <div className="my-6">
      <button
        onClick={() => setShowForm(!showForm)}
        className="bg-green-600 text-white px-4 py-2 rounded hover:bg-green-700"
      >
        {showForm ? 'Cancel' : 'Add New Product'}
      </button>

      {showForm && (
        <form onSubmit={handleSubmit} className="mt-4 max-w-md space-y-4">
          <div>
            <label className="block text-sm font-medium mb-1">Product Name</label>

            <input
              type="text"
              value={formData.productName}
              onChange={(e) =>
                setFormData({
                  ...formData,
                  productName: e.target.value,
                })
              }
              className="w-full border p-2 rounded"
              required
            />
          </div>

          <div>
            <label className="block text-sm font-medium mb-1">Description</label>
            <input
              type="text"
              value={formData.productDescription}
              onChange={(e) =>
                setFormData({
                  ...formData,
                  productDescription: e.target.value,
                })
              }
              className="w-full border p-2 rounded"
            />
          </div>
          <div>
            <label className="block text-sm font-medium mb-1">Price (in cents)</label>

            <input
              type="number"
              value={formData.productPrice}
              onChange={(e) =>
                setFormData({
                  ...formData,
                  productPrice: parseInt(e.target.value),
                })
              }
              className="w-full border p-2 rounded"
              required
            />
          </div>
          <button
            type="submit"
            className="bg-blue-600 text-white px-4 py-2 rounded hover:bg-blue-700"
          >
            Create Product
          </button>
        </form>
      )}
    </div>
  );
}

This component only renders after the merchant has completed onboarding (the if (!accountId || needsOnboarding) return null check at the top). It toggles a form where the merchant enters a product name, description, and price in cents. When submitted, it calls your /api/create-product endpoint, which creates both the product and its price on the merchant’s connected Stripe account.

The price field uses cents because that is what Stripe expects. So if a merchant wants to sell a product for \(25.00, they enter 2500. In a production app, you would add a friendlier input that lets merchants type \)25.00 and converts it to cents automatically.

How to Build the Main Page

Finally, put it all together in app/page.tsx:

'use client';
import { AccountProvider } from '@/contexts/AccountContext';
import ConnectOnboarding from '@/components/ConnectOnboarding';
import Products from '@/components/Products';
import ProductForm from '@/components/ProductForm';
export default function Home() {
  return (
    <AccountProvider>
      {' '}
      <main className="max-w-6xl mx-auto p-8">
        <h1 className="text-3xl font-bold mb-8"> Marketplace Dashboard </h1>
        <ConnectOnboarding />
        <ProductForm />
        <Products />
      </main>
    </AccountProvider>
  );
}

How to Test the Full Flow

Start both servers:

# Terminal 1 - Backend
cd server
npm run dev
 
# Terminal 2 - Frontend
cd client
npm run dev
 
# Terminal 3 - Stripe webhook listener
stripe listen --forward-to localhost:4242/api/webhook

Now test the complete flow:

1. Go to http://localhost:3000 and enter an email to create a merchant account.

2. Click "Complete Onboarding" and fill out Stripe’s test onboarding form. Use test data like 000-000-0000 for the phone number and 0000 for the last four digits of SSN.

3. Wait a few seconds for the account status to update. Once charges are active, you can add products.

4. Create a product using the product form (set the price in cents — for example, 2500 for $25.00).

5. Click "Buy Now" on a product to start the checkout flow.

6. On Stripe’s checkout page, use the test card number 4242 4242 4242 4242 with any future expiry date and any CVC.

7. Check your terminal — you should see the webhook event confirming the payment.

8. Check the Stripe Dashboard to see the payment, the application fee, and the transfer to the connected account.

How the Payment Split Works

Here is exactly what happens when a customer pays $25.00 for a product:

1. The customer pays $25.00 on Stripe’s checkout page.

2. Stripe deducts its processing fee (approximately 2.9% + $0.30 for US cards).

3. Your platform takes the application fee you set ($1.23 in our example).

4. The remaining amount is transferred to the merchant’s connected Stripe account.

5. The merchant can withdraw their funds to their bank account from the Stripe Dashboard.

You control the application fee in the checkout route. In a production marketplace, you would calculate this as a percentage of the transaction. For example, to take a 10% fee:

onst applicationFee = Math.round(
  (price.unit_amount ?? 0) * 0.1
);

Next Steps

You now have a working marketplace. Here are improvements to consider for production:

• Add authentication with NextAuth.js so merchants can securely log in and manage their accounts across sessions.

• Add runtime validation with Zod to validate all request bodies before they reach Stripe.

• Add image uploads for products using Cloudinary or AWS S3, then pass the image URL to Stripe’s product metadata.

• Build separate merchant and customer views. Right now the app combines both experiences on one page.

• Deploy your backend to Railway or Render and your frontend to Vercel. Update the webhook URL in your Stripe Dashboard to point to your production server.

You can find the complete source code for this tutorial on GitHub: https://github.com/michaelokolo/marketplace

Acknowledgements

Some API usage patterns in this tutorial are inspired by examples from the official Stripe documentation. These examples were adapted to demonstrate how to build a complete multi-vendor marketplace architecture.

Conclusion

In this handbook, you built a complete online marketplace where merchants can onboard through Stripe Connect, create products stored directly in Stripe, and receive payments from customers — all without a traditional database.

You learned how to use Stripe’s V2 Accounts API for merchant onboarding, create products and prices on connected accounts, build a checkout flow that handles both one-time payments and subscriptions, listen for payment events with webhooks, and give customers a billing portal to manage their subscriptions.

The key insight is that Stripe Connect handles the hardest parts of running a marketplace — payment splitting, tax compliance, identity verification, and fund transfers. Your job is to build a great user experience on top of it.

If you found this tutorial helpful, share it with someone who is learning to build full-stack applications. Happy coding!

Then the project grows. Features multiply. A second app appears, maybe a separate admin dashboard, a marketing site, or a mobile-facing API. Suddenly, you're copying components between repos, duplicating business logic, arguing over where auth utilities belong, and asking yourself: where did it all go wrong?

The answer is almost always architecture, or rather, the absence of one. Not the kind that lives in a Notion doc but the kind baked into your folder structure, your module boundaries, and the tools you reach for at the start of a project (not after it's already broken).

This article is a practical guide to building layered, reusable architecture in Next.js.

You'll learn about the App Router's colocation model, building scalable folder structures around features, sharing logic across apps with Turborepo, drawing clean data-fetching boundaries using Server Components, designing a testing strategy that matches your layer structure, and wiring up a CI/CD pipeline that only builds and tests what actually changed.

By the end, you'll have a blueprint you can actually use, not just admire.

Table of Contents

• The Core Problem: Coupling Without Intention

• Layer 1: The App Router and Colocation

• Layer 2: Feature-Based Folder Structure

• Layer 3: Monorepo with Turborepo (Sharing Logic Across Apps)

• Layer 4: Server Components and Data-Fetching Boundaries

• Layer 5: Testing Strategy for a Layered Codebase

• Layer 6: CI/CD with Turborepo

• Putting It All Together: The Full Blueprint

• Common Pitfalls and How to Avoid Them

• Final Thoughts

The Core Problem: Coupling Without Intention

When a component reaches directly into a global store, when a page imports a utility from three directories away, when your auth logic is spread across /lib, /helpers, and /utils with no clear owner, every file knows too much about every other file.

The app still runs. But now changing one thing breaks three others, onboarding takes a week, and adding a second app means copying half the first one.

Layered architecture solves this by giving everything a place, and making those places mean something.

Layer 1: The App Router and Colocation

Next.js 13+ introduced the App Router with a file-system-based routing model that does something subtly powerful: it lets you colocate everything related to a route inside that route's folder.

Before the App Router, pages lived in /pages, components lived in /components, and data fetching was scattered. The App Router flips this. A route segment can now own its layout, its loading and error states, its server actions, and even its local components, all in one place.

What Colocation Actually Means

Consider a /dashboard route. In the App Router model, its folder might look like this:

app/
  dashboard/
    page.tsx              # The route entry point
    layout.tsx            # Dashboard-specific shell/navigation
    loading.tsx           # Streaming loading state
    error.tsx             # Error boundary
    components/
      StatsCard.tsx       # Used only within dashboard
      ActivityFeed.tsx
    lib/
      queries.ts          # Data fetching for this route only
      formatters.ts       # Dashboard-specific transforms

The key insight: StatsCard.tsx and queries.ts don't belong to your whole application, they belong to /dashboard. When you delete or refactor the dashboard, you delete or refactor one folder. Nothing else breaks.

This is colocation. It's not a new idea, but the App Router makes it idiomatic in Next.js for the first time.

The Rule of Proximity

A good heuristic: a file should live as close as possible to where it's used. If it's used in one route, it lives in that route's folder. If it's used by two routes under the same parent segment, it moves up one level. If it's used across the entire app, it belongs in a shared layer (more on that shortly).

app/
  (marketing)/          # Route group , no URL segment
    layout.tsx          # Shared layout for marketing pages
    page.tsx
    about/
      page.tsx
  (dashboard)/
    layout.tsx          # Different shell for app routes
    dashboard/
      page.tsx
    settings/
      page.tsx

Route groups (folders wrapped in parentheses) let you share layouts across segments without polluting the URL. This is a clean way to separate concerns, marketing pages and app pages can have entirely different shells without any URL trickery.

Layer 2: Feature-Based Folder Structure

Colocation handles the route level. But large applications have cross-cutting concerns – things that don't belong to any single route but aren't generic utilities either.

This is where most projects fall apart: the /components folder becomes a dumping ground, /lib becomes a junk drawer, and nobody agrees on where useAuth should live.

Feature-based folder structure brings order to this chaos.

Organising by Domain, Not by File Type

Instead of grouping files by what they are (components, hooks, utils), group them by what they do.

src/
  features/
    auth/
      components/
        LoginForm.tsx
        AuthGuard.tsx
      hooks/
        useAuth.ts
        useSession.ts
      lib/
        tokenStorage.ts
        validators.ts
      types.ts
      index.ts            # Public API , only export what others need

    billing/
      components/
        PricingTable.tsx
        SubscriptionBadge.tsx
      hooks/
        useSubscription.ts
      lib/
        stripe.ts
      types.ts
      index.ts

    notifications/
      ...

Each feature folder is a self-contained unit. It has its own components, hooks, utilities, and types. Crucially, it has a barrel file (index.ts) that defines its public API, the things other parts of the app are allowed to import.

Enforcing Boundaries with Barrel Exports

The index.ts is not optional. It's the mechanism that prevents features from becoming entangled.

// features/auth/index.ts
export { LoginForm } from './components/LoginForm';
export { AuthGuard } from './components/AuthGuard';
export { useAuth } from './hooks/useAuth';
export type { AuthUser, AuthState } from './types';

// NOT exported, internal implementation detail:
// tokenStorage.ts, validators.ts

Now, the rest of your app imports from @/features/auth, never from @/features/auth/lib/tokenStorage. If you refactor how tokens are stored internally, nothing outside the feature breaks. This is the essence of encapsulation, not just as a theoretical principle, but as a structural one enforced by your folder layout.

Shared vs. Feature

Not everything belongs in a feature. Truly generic utilities: a cn() classname helper, a date formatter, or a base HTTP client, for example, belong in a shared layer:

src/
  shared/
    components/
      Button.tsx
      Modal.tsx
      Spinner.tsx
    hooks/
      useDebounce.ts
      useMediaQuery.ts
    lib/
      http.ts
      dates.ts
    ui/              # shadcn/ui or design system components

The rule: shared/ has zero knowledge of any feature. Features can import from shared/. shared/ never imports from a feature.

Layer 3: Monorepo with Turborepo (Sharing Logic Across Apps)

Single-repo architecture gets you far, but most teams eventually end up with multiple apps: a customer-facing Next.js app, an admin panel, a separate marketing site, maybe a set of API services.

The question becomes: how do you share code between them without copy-pasting?

The answer is a monorepo with shared packages, and Turborepo is currently the best tool for Next.js teams doing this.

The Monorepo Shape

A well-structured Turborepo looks like this:

my-platform/
  apps/
    web/              # Customer-facing Next.js app
    admin/            # Internal admin panel (also Next.js)
    marketing/        # Marketing site
  packages/
    ui/               # Shared component library
    config/           # Shared ESLint, TypeScript, Tailwind configs
    auth/             # Shared auth utilities and types
    database/         # Prisma client + query helpers
    utils/            # Generic utilities
  turbo.json
  package.json        # Root workspace config

apps/ contains deployable applications. packages/ contains shared code that apps depend on. Neither app imports directly from the other, all sharing flows through packages/.

Setting Up a Shared Package

A package is just a folder with a package.json that other workspace members can depend on.

// packages/ui/package.json
{
  "name": "@my-platform/ui",
  "version": "0.0.1",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": "./src/index.ts"
  }
}

// packages/ui/src/index.ts
export { Button } from './Button';
export { Modal } from './Modal';
export { Card } from './Card';

Now your apps consume it like any npm package:

// apps/web/package.json
{
  "dependencies": {
    "@my-platform/ui": "*"
  }
}

// apps/web/app/dashboard/page.tsx
import { Card, Button } from '@my-platform/ui';

Change Card once in packages/ui, and every app that uses it gets the update, no copy-pasting, no drift.

Important: Because the package points directly at TypeScript source files (not compiled output), each consuming Next.js app must tell the bundler to transpile it. Add this to your Next.js config:

// apps/web/next.config.ts
const config: import('next').NextConfig = {
  transpilePackages: ['@my-platform/ui', '@my-platform/auth', '@my-platform/utils'],
};

export default config;

Without this, the build fails with syntax errors, Next.js doesn't transpile packages from node_modules or workspace dependencies by default. The alternative is compiling each package to dist/ and pointing exports there, but that adds a build step to every package and slows down the dev feedback loop. For internal monorepo packages, transpilePackages is the simpler tradeoff.

The turbo.json Pipeline

Turborepo's real power is its build pipeline. It understands the dependency graph between your packages and apps, caches build outputs, and runs tasks in parallel where possible.

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    }
  }
}

The ^build syntax means: before building this package, build all its dependencies first. So if apps/web depends on packages/ui, Turborepo ensures packages/ui is built before apps/web starts. Remote caching means if packages/ui hasn't changed, Turborepo skips rebuilding it entirely, even across CI runs and team members' machines.

What Goes in a Package vs. an App

A useful litmus test:

If two apps need the same logic, it goes in a package. If only one app needs it, it stays in that app, even if you think the other app might need it someday. Premature abstraction is just as damaging as none at all.

Layer 4: Server Components and Data-Fetching Boundaries

The App Router's Server Components model is arguably the most architecturally significant change Next.js has ever shipped, and also the most misunderstood.

Most developers approach it as a performance optimisation. It is that, but it's more importantly an architectural boundary. Understanding where that boundary sits, and designing around it deliberately, is what separates scalable App Router codebases from ones that fight the framework.

The Mental Model: Two Worlds

Every component in the App Router lives in one of two worlds:

Server Components (default) run exclusively on the server. They can await data directly, access databases, read environment variables, and reduce the JavaScript sent to the browser. They can't use browser APIs, useState, useEffect, or event handlers.

Client Components ('use client') run in the browser (and also during SSR/hydration). They can use hooks, handle events, and access browser APIs. They can't directly await server-side resources.

The directive 'use client' doesn't mean "this runs only in the browser" , it means "this is the boundary where the server-to-client handoff begins." Any module imported by a Client Component becomes part of the client bundle.

But Server Components passed as props (typically via children) retain their server-only nature, they're rendered on the server and streamed as HTML, not included in the client bundle. This distinction is what makes the composition pattern below work.

Designing the Boundary

The goal is to push the 'use client' boundary as far down the tree as possible, keeping data fetching and heavy logic on the server, and reserving Client Components for genuinely interactive leaves.

A pattern that works well in practice:

// app/dashboard/page.tsx , Server Component
// Fetches data, no 'use client' directive needed

import { getMetrics } from '@/features/analytics/lib/queries';
import { MetricsDashboard } from './components/MetricsDashboard';

export default async function DashboardPage() {
  const metrics = await getMetrics();   // Direct DB call , no API round-trip
  return <MetricsDashboard data={metrics} />;
}

// app/dashboard/components/MetricsDashboard.tsx , Server Component
// Composes layout, delegates interactivity to leaves

import { StatsCard } from './StatsCard';
import { ChartSection } from './ChartSection';

export function MetricsDashboard({ data }) {
  return (
    <div className="grid gap-6">
      <StatsCard value={data.revenue} label="Revenue" />
      <ChartSection points={data.trend} />
    </div>
  );
}

// app/dashboard/components/ChartSection.tsx , Client Component
// Interactive chart needs browser APIs

'use client';

import { useState } from 'react';
import { LineChart, RangeSelector } from '@my-platform/ui';

export function ChartSection({ points }) {
  const [range, setRange] = useState('7d');
  return (
    <div>
      <RangeSelector value={range} onChange={setRange} />
      <LineChart data={points.filter(/* range logic */)} />
    </div>
  );
}

The data flows from server to client in one direction. The server does the expensive work (database query), passes serialisable data down as props, and the client receives a ready-to-render dataset – no loading spinners, no client-side fetch waterfalls.

Colocating Data Fetching with Routes

A powerful pattern enabled by Server Components is colocating data fetching directly with the route that needs it, eliminating the need for global state management in many cases.

app/
  orders/
    page.tsx              # await getOrders() , renders list
    [id]/
      page.tsx            # await getOrder(id) , renders single order
      loading.tsx         # Streaming skeleton while awaiting
      components/
        OrderTimeline.tsx  # Server Component , renders timeline data
        CancelButton.tsx  # 'use client' , needs click handler

Each page fetches its own data, scoped to what it needs. Nested layouts and pages can fetch concurrently when using Promise.all or parallel route segments. And loading.tsx gives you streaming suspense boundaries without writing a single <Suspense> wrapper manually.

When to Use a Fetch Layer vs. Direct Queries

As apps scale, you'll want a consistent approach to data access. A practical pattern:

// packages/database/src/queries/orders.ts
// Runs on the server , can be imported in any Server Component

import { db } from '../client';

export async function getOrdersByUser(userId: string) {
  return db.order.findMany({
    where: { userId },
    include: { items: true },
    orderBy: { createdAt: 'desc' },
  });
}

// packages/database/src/index.ts
export { getOrdersByUser } from './queries/orders';
export { getProductById } from './queries/products';
// ...

Your Server Components import from @my-platform/database. Your Client Components never touch this package: they call API routes or Server Actions if they need to mutate data. This keeps the boundary clean and auditable.

Server Actions for Mutations

Data fetching flows through Server Components, but mutations need their own boundary. Server Actions ('use server') let you define server-side functions that Client Components can call directly – no API route boilerplate needed.

// app/orders/[id]/actions.ts
'use server';

import { db } from '@my-platform/database';
import { revalidatePath } from 'next/cache';

export async function cancelOrder(orderId: string) {
  await db.order.update({
    where: { id: orderId },
    data: { status: 'cancelled', cancelledAt: new Date() },
  });

  revalidatePath(`/orders/${orderId}`);
}

// app/orders/[id]/components/CancelButton.tsx
'use client';

import { cancelOrder } from '../actions';
import { useTransition } from 'react';

export function CancelButton({ orderId }: { orderId: string }) {
  const [isPending, startTransition] = useTransition();

  return (
    <button
      disabled={isPending}
      onClick={() => startTransition(() => cancelOrder(orderId))}
    >
      {isPending ? 'Cancelling...' : 'Cancel Order'}
    </button>
  );
}

The architectural decision:

• use Server Actions for mutations that are colocated with a specific route (cancelling an order, updating a profile).

• Use API routes for mutations that are consumed by external clients (webhooks, mobile apps, third-party integrations).

Server Actions keep mutation logic close to the UI that triggers it. API routes provide a stable contract for external consumers.

This completes the data flow picture: Server Components handle reads, Server Actions handle writes, and Client Components are the interactive surface that connects them.

Layer 5: Testing Strategy for a Layered Codebase

The testing pyramid is one of those concepts that sounds obvious in theory but falls apart in practice, usually because the codebase doesn't have clear boundaries to test against. When everything is tangled, every test becomes an integration test by accident.

The layered architecture you've built changes this: each layer has a defined surface area, so you can test each one at the right level of abstraction.

Test Each Layer at the Right Granularity

The layered architecture maps naturally onto the testing pyramid:

The goal: test shared packages exhaustively, test features thoroughly, test pages for integration correctness, and use E2E only for the flows that matter most.

Not everything needs an E2E test, and treating E2E as the default testing strategy is one of the most expensive mistakes a team can make.

Unit Testing Shared Packages

Packages in packages/ are the easiest to test. They're pure TypeScript with no framework coupling. Use Vitest:

// packages/utils/src/dates.test.ts
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { formatRelativeDate } from './dates';

describe('formatRelativeDate', () => {
  beforeEach(() => {
    // Pin the clock to avoid flaky results near midnight
    vi.useFakeTimers();
    vi.setSystemTime(new Date('2026-03-15T12:00:00Z'));
  });

  afterEach(() => {
    vi.useRealTimers();
  });

  it('returns "today" for dates within the current day', () => {
    expect(formatRelativeDate(new Date())).toBe('today');
  });

  it('returns "yesterday" for dates on the previous day', () => {
    const yesterday = new Date('2026-03-14T15:00:00Z');
    expect(formatRelativeDate(yesterday)).toBe('yesterday');
  });
});

Keep package tests colocated with the source file. A dates.ts file has a dates.test.ts sibling. No separate __tests__ folders, those are relics of less structured codebases.

Testing Feature Modules

Features are where most of your business logic lives, so they get the most test coverage. The key rule: test the public API of the feature, not its internals.

// features/auth/hooks/useAuth.test.ts
import { renderHook, act } from '@testing-library/react';
import { useAuth } from '../hooks/useAuth';
import { createWrapper } from '@/test/utils'; // your test provider wrapper

describe('useAuth', () => {
  it('returns authenticated state when session exists', async () => {
    const { result } = renderHook(() => useAuth(), {
      wrapper: createWrapper({ session: mockSession }),
    });

    expect(result.current.isAuthenticated).toBe(true);
    expect(result.current.user.email).toBe(mockSession.user.email);
  });

  it('redirects to login when session is null', async () => {
    const { result } = renderHook(() => useAuth(), {
      wrapper: createWrapper({ session: null }),
    });

    expect(result.current.isAuthenticated).toBe(false);
  });
});

Notice that the test imports from the hook directly, not from the feature's index.ts barrel. Feature index exports are public APIs. They're tested through integration tests that consume the feature as a whole. Internal hooks and utilities are tested at the unit level. Both are valid, and the distinction is intentional.

Testing Server Components

Server Components are async functions that return JSX. Testing them directly is still an evolving story. React's test renderer doesn't natively handle async components, and calling await DashboardPage() then passing the result to render() produces subtle issues (missing context, act() warnings, or outright failures depending on your setup).

The most reliable approach today is to test the layers separately: mock the data layer to verify it's called correctly, and test the presentational component with static props.

// app/dashboard/components/MetricsDashboard.test.tsx
import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import { MetricsDashboard } from './MetricsDashboard';

describe('MetricsDashboard', () => {
  it('renders revenue metric from provided data', () => {
    render(
      <MetricsDashboard data={{ revenue: 84200, trend: [] }} />
    );

    expect(screen.getByText('£84,200')).toBeInTheDocument();
  });
});

// features/analytics/lib/queries.test.ts
import { describe, it, expect } from 'vitest';
import { getMetrics } from './queries';

describe('getMetrics', () => {
  it('returns revenue and trend data', async () => {
    const metrics = await getMetrics();

    expect(metrics.revenue).toBeGreaterThan(0);
    expect(Array.isArray(metrics.trend)).toBe(true);
  });
});

The key insight: mock at the data layer boundary, not at the database or network layer. The data query has its own tests in packages/database. The presentational component has its own tests with static props. The Server Component page wires them together, and that wiring is verified by your E2E tests, which are better suited to catching integration issues across the async boundary.

End-to-End Tests with Playwright

Reserve Playwright for the flows that touch multiple layers and where a breakage would be catastrophic: authentication, checkout, and form submission with side effects. Don't use it for visual regressions or static content, as that's expensive and slow.

// e2e/auth.spec.ts
import { test, expect } from '@playwright/test';

test('user can log in and reach dashboard', async ({ page }) => {
  await page.goto('/login');
  await page.fill('[name="email"]', 'test@example.com');
  await page.fill('[name="password"]', 'password123');
  await page.click('button[type="submit"]');

  await expect(page).toHaveURL('/dashboard');
  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});

Colocate E2E tests in a top-level e2e/ folder at the monorepo root. They span apps and don't belong inside any single app's directory.

Configuring Vitest Across the Monorepo

Each package and app has its own vitest.config.ts, but they can share a base config via a shared package:

// packages/config/vitest.base.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./src/test/setup.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'lcov'],
    },
  },
});

// apps/web/vitest.config.ts
import { mergeConfig } from 'vitest/config';
import base from '@my-platform/config/vitest.base';

export default mergeConfig(base, {
  test: {
    include: ['src/**/*.test.{ts,tsx}', 'app/**/*.test.{ts,tsx}'],
  },
});

This ensures consistent test configuration across every app and package without duplication.

Layer 6: CI/CD with Turborepo

A well-designed monorepo without a smart CI pipeline is just a big repo. Turborepo's real power emerges in CI, where it can cut build and test times dramatically through caching and intelligent task scheduling.

The Core Insight: Only Run What Changed

Traditional CI pipelines run everything on every commit. In a monorepo, this means running tests for apps/admin when you only changed a utility in apps/web. Turborepo's dependency graph awareness eliminates this.

When you run turbo test, Turborepo:

1. Builds the dependency graph from your package.json files

2. Checks which packages have changed (against the last cached state)

3. Runs tests only for changed packages and their dependents

4. Caches results. If nothing changed, it restores from cache instantly.

A change to packages/ui triggers tests for packages/ui, apps/web, and apps/admin (since both depend on it). A change only to apps/web triggers tests for apps/web only.

Remote Caching

Without remote caching, Turborepo's local cache doesn't help in CI – each run starts fresh. With remote caching, build and test artifacts are stored in the cloud and shared across all CI runners and developers' machines.

# Authenticate with Turborepo remote cache (Vercel)
npx turbo login
npx turbo link

Or use a self-hosted cache server if you need to keep artifacts on your own infrastructure. Once configured, a CI run on a branch that touched only apps/web might take 45 seconds instead of 8 minutes, because every packages/* task restores from cache.

A Production-Ready GitHub Actions Pipeline

Here's a complete pipeline that uses Turborepo's caching, runs affected tasks only, and splits lint, test, and build into parallel jobs:

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ secrets.TURBO_TEAM }}

jobs:
  lint:
    name: Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci
      - run: npx turbo lint --filter="...[origin/main]"

  test:
    name: Test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci
      - run: npx turbo test --filter="...[origin/main]"

  build:
    name: Build
    runs-on: ubuntu-latest
    needs: [lint, test]
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci
      - run: npx turbo build --filter="...[origin/main]"

  e2e:
    name: E2E Tests
    runs-on: ubuntu-latest
    needs: [build]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci
      - run: npx playwright install --with-deps

      - name: Build the app (restores from Turborepo cache if unchanged)
        run: npx turbo build --filter="apps/web"

      - name: Run E2E tests
        run: npx turbo e2e

The E2E job assumes Playwright's webServer config handles starting the app automatically. Configure this in your playwright.config.ts:

// playwright.config.ts
export default defineConfig({
  webServer: {
    command: 'npm run start --prefix apps/web',
    port: 3000,
    reuseExistingServer: !process.env.CI,
  },
});

This way Playwright starts the production server before tests run and tears it down afterwards – no manual server management in CI.

The --filter="...[origin/main]" flag is the critical piece. It tells Turborepo to run tasks only for packages that have changed since the main branch, plus all packages that depend on those changed packages. This is the most impactful optimisation in the whole pipeline.

Filtering Strategies

Turborepo's --filter flag is flexible and worth understanding:

# Only run tasks for packages that changed vs main
turbo test --filter="...[origin/main]"

# Run tasks for a specific app and all its dependencies
turbo build --filter="apps/web..."

# Run tasks for everything except a specific app
turbo test --filter="!apps/admin"

# Run tasks for all apps (not packages)
turbo build --filter="./apps/*"

For most CI pipelines, --filter="...[origin/main]" on feature branches and turbo run test build (no filter) on main merges is the right split. You want fast feedback on PRs and confidence that everything still works on main.

Deployment Pipeline with Per-App Filtering

When deploying to Vercel, Netlify, or any platform with per-app deployments, Turborepo lets you detect which apps actually changed and skip deployments for unchanged ones:

# .github/workflows/deploy.yml
- name: Check if web app changed
  id: check-web
  run: |
    CHANGED=$(npx turbo run build --filter="apps/web...[origin/main]" --dry=json | jq '.packages | length')
    echo "changed=\(CHANGED" >> \)GITHUB_OUTPUT

- name: Deploy web
  if: steps.check-web.outputs.changed != '0'
  run: vercel deploy --prod
  env:
    VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}

This ensures your admin app doesn't trigger a deployment when only the marketing site changed, reducing deploy times, costs, and the blast radius of any deployment failure.

Environment Variable Management

One of the trickier parts of a monorepo CI setup is environment variables: each app needs its own secrets, but some are shared across apps.

A clean convention:

# .env (repo root , shared across all apps in local dev)
DATABASE_URL=...
REDIS_URL=...

# apps/web/.env.local (web-specific overrides)
NEXT_PUBLIC_APP_URL=https://app.example.com
STRIPE_KEY=...

# apps/admin/.env.local (admin-specific)
NEXT_PUBLIC_APP_URL=https://admin.example.com
ADMIN_SECRET=...

In CI, store shared secrets as organisation-level GitHub secrets and app-specific secrets as repository-level secrets scoped to the appropriate environment.

Never store secrets in turbo.json or any committed file. Instead, use env in your pipeline steps and Turborepo's globalEnv field in turbo.json to declare which env vars should bust the cache when they change:

// turbo.json
{
  "globalEnv": ["NODE_ENV", "DATABASE_URL"],
  "tasks": {
    "build": {
      "env": ["NEXT_PUBLIC_APP_URL", "STRIPE_KEY"],
      "dependsOn": ["^build"],
      "outputs": [".next/**"]
    }
  }
}

This tells Turborepo: if DATABASE_URL changes, invalidate the cache for all tasks. If NEXT_PUBLIC_APP_URL changes, only invalidate the build task. Without this, you risk Turborepo restoring a cached build that was compiled against a different environment, a subtle and painful bug.

Putting It All Together: The Full Blueprint

Here's what the complete architecture looks like assembled:

my-platform/
  apps/
    web/
      app/
        (marketing)/
          layout.tsx
          page.tsx
          about/page.tsx
        (app)/
          layout.tsx            # Auth-protected shell
          dashboard/
            page.tsx            # Server Component , fetches data
            loading.tsx
            components/
              MetricsDashboard.tsx
              ChartSection.tsx  # 'use client'
          orders/
            page.tsx
            [id]/
              page.tsx
              components/
                OrderTimeline.tsx
                CancelButton.tsx  # 'use client'
      src/
        features/
          auth/
            components/
            hooks/
            lib/
            index.ts
          billing/
            ...
        shared/
          components/
          hooks/
          lib/
    admin/
      app/
        ...                     # Same layer structure
      src/
        features/
          ...
  packages/
    ui/                         # Shared primitives
    auth/                       # Shared auth logic
    database/                   # Prisma + queries
    config/                     # ESLint, TS, Tailwind configs
    utils/                      # Generic helpers
  turbo.json
  package.json

Notice how the 'use client' boundary appears only at the interactive leaves: ChartSection.tsx needs useState, and CancelButton.tsx needs a click handler and useTransition. Everything above them (MetricsDashboard.tsx, OrderTimeline.tsx, the page components) stays on the server, fetching data and composing layout without shipping any JavaScript to the browser.

The layers stack cleanly:

1. Turborepo packages: the lowest layer. Generic, reusable, no app-specific knowledge.

2. Shared feature layer: cross-cutting app concerns. Can consume packages, knows nothing of routes.

3. Feature modules: domain logic, encapsulated behind barrel exports.

4. App Router: routes, layouts, colocation. Consumes features and packages. Data flows through Server Components, interactivity is delegated to Client Component leaves.

Common Pitfalls and How to Avoid Them

"I'll just put it in /utils for now." This is how junk drawers form. If you can't name what a utility belongs to, it probably needs a new feature folder, not a generic dumping ground.

Over-extracting packages too early: Not everything needs to be a shared package. Start in the app, extract to a package only when a second consumer appears. The cost of premature abstraction is maintenance overhead and false coupling.

Client Components at the top of every tree: If your route's page.tsx has 'use client' at the top, you've lost most of what Server Components give you. Push the directive down to the interactive leaf.

Circular package dependencies: If packages/auth imports from packages/database and packages/database imports from packages/auth, you have a cycle. Keep the dependency graph a DAG: each package should have one clear level of abstraction.

Barrel files that export everything: The barrel file is a public API, not an index of every file in the folder. Export only what other parts of the app are meant to use.

Final Thoughts

Good architecture isn't about finding the perfect structure, it's about making the right decisions easy and the wrong decisions hard.

• Colocation makes it easy to find what you need.

• Feature modules make it hard to accidentally couple unrelated domains.

• Turborepo makes it easy to share code and hard to duplicate it.

• Server Components make it easy to fetch data where you need it and hard to send unnecessary JavaScript to the browser.

None of these ideas are new. Layered architecture, separation of concerns, and encapsulation are decades-old principles. What Next.js and Turborepo give you is a modern toolkit to express them idiomatically in a JavaScript codebase.

The best time to set this up is at the start of a project. The second best time is now, before the next feature makes untangling things twice as hard.

This guide shows you how to share components and data between Server and Client Components in Next.js. You'll learn composition patterns, prop passing rules, and when to use each approach.

Table of Contents

• What are Server and Client Components?

• Prerequisites

• How to Pass Data from Server to Client via Props

• How to Pass Server Components as Children to Client Components

• What Props Are Allowed Between Server and Client

• How to Share Data with Context and React.cache

• How to Use Third-Party Components in Both Environments

• How to Prevent Environment Poisoning with server-only and client-only

• Real-World Examples

• Conclusion

What are Server and Client Components?

In the Next.js App Router, every component is a Server Component by default. Server Components run only on the server. They can fetch data from databases, use API keys, and keep sensitive logic out of the browser. They don't send JavaScript to the client, which reduces bundle size.

Client Components run on both the server (for the initial HTML) and the client (for interactivity). You mark them with the "use client" directive at the top of the file. They can use useState, useEffect, event handlers, and browser APIs like localStorage and window.

The key rule: Server Components can import and render Client Components, but Client Components can't import Server Components directly. They can only receive them as props (such as children).

Prerequisites

Before you follow along, you should have:

• Basic familiarity with React (components, props, hooks)

• A Next.js project using the App Router (Next.js 13 or later)

• Node.js installed (version 18 or later recommended)

If you don't have a Next.js project yet, create one with:

npx create-next-app@latest my-app

How to Pass Data from Server to Client via Props

The simplest way to share data between Server and Client Components is to pass it as props. The Server Component fetches the data, and the Client Component receives it and handles interactivity.

Here is a basic example. A page (Server Component) fetches a post and passes the like count to a LikeButton (Client Component):

// app/post/[id]/page.jsx (Server Component)
import LikeButton from '@/app/ui/like-button';
import { getPost } from '@/lib/data';

export default async function PostPage({ params }) {
  const { id } = await params;
  const post = await getPost(id);

  return (
    <div>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
      <LikeButton likes={post.likes} postId={post.id} />
    </div>
  );
}

// app/ui/like-button.jsx (Client Component)
'use client';

import { useState } from 'react';

export default function LikeButton({ likes, postId }) {
  const [count, setCount] = useState(likes);

  const handleLike = () => {
    setCount((c) => c + 1);
    // Call API or Server Action to persist
  };

  return (
    <button onClick={handleLike}>
      {count} likes
    </button>
  );
}

The Server Component fetches data on the server. The Client Component receives plain values (likes, postId) and manages state and events. This pattern keeps data fetching on the server and interactivity on the client.

How to Pass Server Components as Children to Client Components

You can pass a Server Component as the children prop (or any prop) to a Client Component. The Server Component still renders on the server. The Client Component receives the rendered output, not the component code.

This is useful when you want a Client Component to wrap or control the layout of server-rendered content. For example, a modal that shows server-fetched data:

// app/ui/modal.jsx (Client Component)
'use client';

import { useState } from 'react';

export default function Modal({ children }) {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open</button>
      {isOpen && (
        <div className="modal-overlay">
          <div className="modal-content">{children}</div>
        </div>
      )}
    </>
  );
}

// app/cart/page.jsx (Server Component)
import Modal from '@/app/ui/modal';
import Cart from '@/app/ui/cart';

export default function CartPage() {
  return (
    <Modal>
      <Cart />
    </Modal>
  );
}

// app/ui/cart.jsx (Server Component - no 'use client')
import { getCart } from '@/lib/cart';

export default async function Cart() {
  const items = await getCart();

  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  );
}

Cart is a Server Component that fetches cart data. It's passed as children to Modal, which is a Client Component. The server renders Cart first. The RSC Payload includes the rendered result. The client receives that output and displays it inside the modal. The cart data never runs on the client.

You can use the same pattern with named props (slots):

// app/ui/tabs.jsx (Client Component)
'use client';

import { useState } from 'react';

export default function Tabs({ tabs, children }) {
  const [activeIndex, setActiveIndex] = useState(0);

  return (
    <div>
      <div className="tab-list">
        {tabs.map((tab, i) => (
          <button
            key={tab.id}
            onClick={() => setActiveIndex(i)}
            className={activeIndex === i ? 'active' : ''}
          >
            {tab.label}
          </button>
        ))}
      </div>
      <div className="tab-content">{children[activeIndex]}</div>
    </div>
  );
}

// app/dashboard/page.jsx (Server Component)
import Tabs from '@/app/ui/tabs';
import Overview from '@/app/ui/overview';
import Analytics from '@/app/ui/analytics';

export default function DashboardPage() {
  const tabs = [
    { id: 'overview', label: 'Overview' },
    { id: 'analytics', label: 'Analytics' },
  ];

  return (
    <Tabs tabs={tabs}>
      <Overview />
      <Analytics />
    </Tabs>
  );
}

Overview and Analytics can be Server Components that fetch their own data. They render on the server, and the client receives the pre-rendered output.

What Props Are Allowed Between Server and Client

Props passed from Server Components to Client Components must be serializable. React serializes them into the RSC Payload so they can be sent to the client.

Allowed Types

• Strings, numbers, booleans

• null and undefined

• Plain objects (no functions, no class instances)

• Arrays of serializable values

• JSX (Server Components as children or other props)

• Server Actions (functions with "use server")

Not Allowed

• Functions (except Server Actions)

• Date objects

• Class instances

• Symbols

• Map, Set, WeakMap, WeakSet

• Objects with custom prototypes

• Buffers, ArrayBuffer, typed arrays

If you need to pass a Date, convert it to a string or number first:

<ClientComponent createdAt={post.createdAt.toISOString()} />

If you use MongoDB, convert ObjectId to a string:

<PostThread userId={user._id.toString()} />

Passing Server Actions as props

Server Actions are async functions marked with "use server". You can pass them as props to Client Components. They are serialized by reference, not by value.

// app/actions/post.js
'use server';

export async function likePost(postId) {
  // Update database
  revalidatePath(`/post/${postId}`);
}

// app/post/[id]/page.jsx (Server Component)
import LikeButton from '@/app/ui/like-button';
import { likePost } from '@/app/actions/post';

export default async function PostPage({ params }) {
  const post = await getPost((await params).id);

  return <LikeButton likes={post.likes} postId={post.id} onLike={likePost} />;
}

// app/ui/like-button.jsx (Client Component)
'use client';

export default function LikeButton({ likes, postId, onLike }) {
  const handleClick = () => {
    onLike(postId);
  };

  return <button onClick={handleClick}>{likes} likes</button>;
}

You can also bind arguments:

<LikeButton onLike={likePost.bind(null, post.id)} />

How to Share Data with Context and React.cache

React Context doesn't work in Server Components. To share data between Server and Client Components, you can combine a Client Component context provider with React.cache for server-side memoization.

Create a cached fetch function:

// lib/user.js
import { cache } from 'react';

export const getUser = cache(async () => {
  const res = await fetch('https://api.example.com/user');
  return res.json();
});

Create a provider that accepts a promise and stores it in context:

// app/providers/user-provider.jsx
'use client';

import { createContext } from 'react';

export const UserContext = createContext(null);

export default function UserProvider({ children, userPromise }) {
  return (
    <UserContext.Provider value={userPromise}>
      {children}
    </UserContext.Provider>
  );
}

In your root layout, pass the promise without awaiting it:

// app/layout.jsx
import UserProvider from '@/app/providers/user-provider';
import { getUser } from '@/lib/user';

export default function RootLayout({ children }) {
  const userPromise = getUser();

  return (
    <html>
      <body>
        <UserProvider userPromise={userPromise}>{children}</UserProvider>
      </body>
    </html>
  );
}

Client Components use use() to unwrap the promise:

// app/ui/profile.jsx
'use client';

import { use, useContext } from 'react';
import { UserContext } from '@/app/providers/user-provider';

export default function Profile() {
  const userPromise = useContext(UserContext);
  if (!userPromise) {
    throw new Error('Profile must be used within UserProvider');
  }
  const user = use(userPromise);

  return <p>Welcome, {user.name}</p>;
}

Wrap the component in Suspense for loading states:

// app/dashboard/page.jsx
import { Suspense } from 'react';
import Profile from '@/app/ui/profile';

export default function DashboardPage() {
  return (
    <Suspense fallback={<div>Loading profile...</div>}>
      <Profile />
    </Suspense>
  );
}

Server Components can call getUser() directly. Because it's wrapped in React.cache, multiple calls in the same request return the same result:

// app/settings/page.jsx
import { getUser } from '@/lib/user';

export default async function SettingsPage() {
  const user = await getUser();
  return <h1>Settings for {user.name}</h1>;
}

React.cache is scoped per request. Each request has its own memoization – there's no sharing across requests.

How to Use Third-Party Components in Both Environments

Some third-party components use useState, useEffect, or browser APIs but don't have "use client" in their source. If you use them in a Server Component, you'll get an error.

Wrap them in your own Client Component:

// app/ui/carousel-wrapper.jsx
'use client';

import { Carousel } from 'acme-carousel';

export default Carousel;

Now you can use it in a Server Component:

// app/gallery/page.jsx
import Carousel from '@/app/ui/carousel-wrapper';

export default function GalleryPage() {
  return (
    <div>
      <h1>Gallery</h1>
      <Carousel />
    </div>
  );
}

If the third-party component is already used inside a Client Component, you don't need a wrapper. The parent's "use client" boundary is enough:

'use client';

import { Carousel } from 'acme-carousel';

export default function Gallery() {
  return <Carousel />;
}

How to Prevent Environment Poisoning with server-only and client-only

It's easy to accidentally import server-only code (database clients, API keys) into a Client Component. To catch this at build time, use the server-only package.

Install it:

npm install server-only

Add it at the top of files that must never run on the client:

// lib/data.js
import 'server-only';

export async function getSecretData() {
  const res = await fetch('https://api.example.com/data', {
    headers: {
      authorization: process.env.API_KEY,
    },
  });
  return res.json();
}

If you import getSecretData (or any symbol from this file) into a Client Component, the build will fail with a clear error.

For client-only code (for example, code that uses window), use client-only:

npm install client-only

// lib/analytics.js
import 'client-only';

export function trackEvent(name) {
  if (typeof window !== 'undefined') {
    window.analytics?.track(name);
  }
}

Importing this into a Server Component will cause a build error.

Real-World Examples

Example 1: Layout with Shared Server and Client Pieces

Keep the layout as a Server Component. Only the interactive parts are Client Components:

// app/layout.jsx (Server Component)
import Logo from '@/app/ui/logo';
import Search from '@/app/ui/search';

export default function Layout({ children }) {
  return (
    <html>
      <body>
        <nav>
          <Logo />
          <Search />
        </nav>
        <main>{children}</main>
      </body>
    </html>
  );
}

// app/ui/logo.jsx (Server Component - no directive)
export default function Logo() {
  return <img src="/logo.svg" alt="Logo" />;
}

// app/ui/search.jsx (Client Component)
'use client';

import { useState } from 'react';

export default function Search() {
  const [query, setQuery] = useState('');

  return (
    <input
      type="search"
      value={query}
      onChange={(e) => setQuery(e.target.value)}
    />
  );
}

Logo stays on the server. Search is interactive and runs on the client. The layout composes both.

Example 2: Product Page with Server Data and Client Add-to-Cart

// app/product/[id]/page.jsx (Server Component)
import { getProduct } from '@/lib/products';
import AddToCartButton from '@/app/ui/add-to-cart-button';

export default async function ProductPage({ params }) {
  const { id } = await params;
  const product = await getProduct(id);

  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <p>${product.price}</p>
      <AddToCartButton productId={product.id} price={product.price} />
    </div>
  );
}

// app/ui/add-to-cart-button.jsx (Client Component)
'use client';

import { useState } from 'react';

export default function AddToCartButton({ productId, price }) {
  const [added, setAdded] = useState(false);

  const handleClick = () => {
    // Call Server Action or API
    setAdded(true);
  };

  return (
    <button onClick={handleClick} disabled={added}>
      {added ? 'Added!' : `Add to Cart - $${price}`}
    </button>
  );
}

Example 3: Theme Provider Wrapping Server Content

// app/providers/theme-provider.jsx (Client Component)
'use client';

import { createContext, useContext, useState } from 'react';

const ThemeContext = createContext('light');

export function useTheme() {
  return useContext(ThemeContext);
}

export default function ThemeProvider({ children }) {
  const [theme, setTheme] = useState('light');

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

// app/layout.jsx (Server Component)
import ThemeProvider from '@/app/providers/theme-provider';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

ThemeProvider is a Client Component. It wraps children, which can be Server Components. Render providers as deep as possible in the tree so Next.js can optimize static Server Components.

Example 4: Shared Utility Without Directives

Pure utilities (no hooks, no browser APIs) can be shared. They run in the environment of the component that imports them:

// lib/format.js (shared - no directive)
export function formatPrice(amount) {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD',
  }).format(amount);
}

// Server Component
import { formatPrice } from '@/lib/format';

export default async function ProductPage() {
  const product = await getProduct();
  return <p>{formatPrice(product.price)}</p>;
}

// Client Component
'use client';

import { formatPrice } from '@/lib/format';

export default function PriceDisplay({ amount }) {
  return <span>{formatPrice(amount)}</span>;
}

formatPrice is a pure function. It works in both Server and Client Components.

Conclusion

Sharing components and data between Server and Client Components in Next.js comes down to a few patterns:

• Pass data as props – Server Components fetch data and pass serializable values to Client Components.

• Pass Server Components as children – Client Components can wrap server-rendered content via children or slot props.

• Use serializable props only – Stick to primitives, plain objects, arrays, and Server Actions. Convert Date and ObjectId to strings.

• Share data with Context + React.cache – Use a Client Component provider that receives a promise and React.cache for server-side deduplication.

• Wrap third-party components – Add "use client" wrappers for libraries that use client-only features.

• Use server-only and client-only – Prevent accidental imports across the server/client boundary.

Keep Server Components at the top of the tree and push Client Components down to leaf nodes. This reduces JavaScript sent to the browser while keeping interactivity where you need it.

The main technologies used are Next.js and Mux. This project will help you understand how professional video sites actually work. The project features:

• Browser-Based Recording: Capture your screen and microphone directly in the browser using standard media APIs.

• Smart Uploads: Use "Direct Upload" to send videos straight to the cloud, which saves server bandwidth and memory.

• AI Integration: Automatically transcribe audio via OpenAI’s Whisper model and generate video titles and tags using Mux AI.

• Modern Video Tech: Learn how HLS and Adaptive Bitrate Streaming provide smooth playback by switching quality levels based on internet speed.

• Professional Features: Add custom watermarks to your videos and create a dashboard with animated thumbnails.

Watch the full course on the freeCodeCamp.org YouTube channel (1-hour watch).

Why does this happen? The authentication worked, the session is valid, the user is authenticated, but the authorization failed.

This specific issue is called IDOR (Insecure Direct Object Reference). It’s one of the most common security bugs and is categorized under Broken Object Level Authorization (BOLA) in the OWASP API Security Top 10.

In this tutorial, you’ll learn:

• Why IDOR happens

• Why authentication alone is not enough

• How object-level authorization works

• How to fix IDOR properly in Next.js API routes

• How to design safer APIs from the start

Table of Content

• Table of Content

• Authentication vs. Authorization

• What is an IDOR Vulnerability?

• The Vulnerable Pattern in Next.js

• How to Handle IDOR in Next.js

  • Object-Level Authorization

• How to Design Safer Endpoints (/api/me)

• Mental Model for API Design

• Conclusion

Authentication vs. Authorization

Before writing further, let’s clarify something critical.

• Authentication answers: Who are you?

• Authorization answers: What are you allowed to access?

In IDOR scenarios, authentication works (the user is logged in), while authorization is missing or incomplete. That distinction is the core lesson of this article.

What is an IDOR Vulnerability?

An IDOR vulnerability happens when your API fetches a resource by an identifier (like a user ID), and then you do not verify that the requester owns or is allowed to access that resource.

Example of such a request:

GET /api/users/123

The code above is an HTTP GET request to the /api/users/123 route. The GET method is used to request data from the server. This indicates that the client is requesting a specific user with the ID 123 and this request returns the user data in a response (often in JSON format).

If your backend makes the request using a similar structure to the code snippet below without checking who is making the request, you have an IDOR vulnerability, even if the user is logged in.

db.user.findUnique({ where: { id: "123" } })

What the code does is to query the database for a single user record. The db.user part refers to the user model/table and findUnique() is a method that returns only one record based on a unique field. Inside the method, the where clause specifies the filter condition and { id: "123" } tells the database to find the user whose unique id equals "123". If a matching record exists, it returns that user object; otherwise, it returns null.

The Vulnerable Pattern in Next.js

Looking at this Next.js App Router API route:

// app/api/users/[id]/route.ts
import { NextResponse } from "next/server";
import { db } from "@/lib/db";

export async function GET(
  req: Request,
  { params }: { params: { id: string } }
) {
  const user = await db.user.findUnique({
    where: { id: params.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

Before going to the implication of this code snippet, let's understand what the code does. It defines a dynamic API route for /api/users/[id]. The exported GET function is an async route handler that runs when a GET request is made to this endpoint. It receives the request object and a params object, where params.id contains the dynamic [id] in the URL segment. The db.user.findUnique() method queries the database for a user whose id matches params.id, and the select option limits the returned fields to id, email, and name. Finally, NextResponse.json() sends the retrieved user data back to the client as a JSON response.

Now, to the implication, the code is a bad approach because the route accepts a user ID from the URL, fetches that user directly from the database, and returns the result. There is no session validation, no ownership check, and no role check.

If a logged-in user changes the id in the URL, they may access other users’ data. This is simply IDOR.

How to Handle IDOR in Next.js

The first element of defense is verifying identity. We’ll use getServerSession from NextAuth (adjust if using another auth provider). This change ensures that you read the session from the cookies, verify it on the server side, and ensure the user has a valid ID. This prevents unauthenticated access.

// lib/auth.ts
import { getServerSession } from "next-auth";
import { authOptions } from "@/lib/authOptions";

export async function requireSession() {
  const session = await getServerSession(authOptions);

  if (!session?.user?.id) {
    return null;
  }

  return session;
}

The code above defines an authentication helper function called requireSession. The getServerSession(authOptions) function retrieves the current user session on the server using the provided authentication configuration. The optional chaining (session?.user?.id) in the if block that follows safely checks whether a logged-in user and their id exist. If no valid session or user ID is found, the function returns null, indicating the request is unauthenticated. Otherwise, it returns the full session object so it can be used in protected routes or server logic.

You have successfully confirmed that the user and session exist; now, update the route:

export async function GET(
  req: Request,
  { params }: { params: { id: string } }
) {
  const session = await requireSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const user = await db.user.findUnique({
    where: { id: params.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

The fix is incomplete yet, but in the above code, you’ve prevented anonymous access. The GET handler calls the requireSession() that was created earlier to verify that the request is authenticated. If no valid session is returned, it immediately responds with a JSON error message and a 401 Unauthorized HTTP status. If the user is authenticated, it proceeds to call db.user.findUnique() to fetch the user whose id matches params.id, selecting only the id, email, and name fields. Finally, it returns the retrieved user data as a JSON response using NextResponse.json().

Something is still missing. Can you guess? Any authenticated user can still request any resource by changing the URL path to the request they want. How? This leads us to object-level authorization.

Object-Level Authorization

An object-level authorization ensures that a user can only access their own data (unless explicitly permitted).

The improvement to the code would be to add an ownership check. The adjustment ensures the API request checks if the requester is authenticated and owns the requested object. If either fails, access is denied.

export async function GET(
  req: Request,
  { params }: { params: { id: string } }
) {
  const session = await requireSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  if (session.user.id !== params.id) {
    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
  }

  const user = await db.user.findUnique({
    where: { id: params.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

Let's take a look at what happened in the code, the GET handler first authenticates the request using requireSession(), returning a 401 response if no valid session exists. It then performs an authorization check by comparing session.user.id with params.id. If they do not match, it returns a 403 Forbidden response, preventing users from accessing other users’ data. If both checks pass, it queries the database using db.user.findUnique() to retrieve the specified user and limits the result to selected fields. Finally, it sends the user data back as a JSON response. With this, you’ve enforced an object-level authorization.

How to Design Safer Endpoints (/api/me)

The safest approach in designing your endpoint is to eliminate the risk entirely. Instead of allowing users to specify IDs (/api/users/:id), use /api/me, because the server already knows the user’s identity from the session.

// app/api/me/route.ts
export async function GET() {
  const session = await requireSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const user = await db.user.findUnique({
    where: { id: session.user.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

This approach makes sure that your API only returns data for the currently authenticated user. It first calls requireSession() to ensure the request is authenticated, returning a 401 response if no session exists. Instead of using a URL parameter, it reads the user’s ID directly from session.user.id, ensuring the user can only access their own data. It then calls db.user.findUnique() to retrieve that user from the database, selecting only specific fields, and returns the result as a JSON response.

You can be confident with this approach because the client cannot manipulate user IDs. The server gets the user identity from a trusted source, and the attack surface is reduced. This is called secure-by-design API model.

Now, you should clearly understand that authentication does not imply authorization. Hence,

• IDOR occurs when object ownership is not verified

• Every API route that accepts an ID must validate access

• Safer API design reduces vulnerability surface

• Authorization must always run on the server

Mental Model for API Design

When writing any API route, answer these questions:

1. Who is making this request?

2. What object are they requesting?

3. Does policy allow them to access it?

If you cannot clearly answer all three, your route may be vulnerable.

Conclusion

IDOR vulnerabilities happen when APIs trust user-supplied identifiers without verifying ownership or permission.

To prevent them in Next.js, authenticate every private route, enforce object-level authorization, centralize authorization logic, and write tests for forbidden access.

Security is not about adding logins, it’s about enforcing security policy on every object access.

In this article, we’ll build a real, production-ready feature flag system, not just a simple boolean toggle.

Specifically, we’ll implement:

• A global on/off flag to enable or disable features instantly

• User-specific flags to grant access to individual users (for beta testing or internal users)

• Percentage-based rollouts to gradually expose features to a subset of users

• A React-powered admin dashboard to manage flags without redeploying

• Client-side and server-side enforcement, so features are gated consistently everywhere

By the end, we’ll finish by wiring a real Todo feature behind a feature flag, showing how entire pages and components can be safely toggled on and off in production.

Table of Contents

• What Are Feature Flags?

• Prerequisites

• Project Setup

• Database Schema Design

• Setting Up Supabase

• Building the Core Feature Flag Logic

• Setting Up React Query

• Creating the React Hook

• Building the Admin Dashboard

• Implementing a Real-World Example

• Server-Side Usage

• Why React Query?

• Conclusion

Prerequisites

Before you begin, make sure you have:

• Node.js 18 or higher installed

• A basic understanding of React and Next.js

• Familiarity with TypeScript

• A Supabase account (free tier works perfectly)

• A code editor like VS Code

• Basic understanding of React Query (TanStack Query) for server state management

What Are Feature Flags?

Feature flags (also called feature toggles) are configuration mechanisms that let you enable or disable features in your application without changing code. Think of them as light switches for your features.

Here are some common use cases:

• Gradual rollouts: Release a feature to 10% of users first, then gradually increase

• User-specific access: Enable features for beta testers or VIP users

• Emergency kill switches: Instantly disable a feature if something goes wrong

• A/B testing: Test different versions of features with different user groups

Project Setup

Start by creating a new Next.js project with TypeScript:

npx create-next-app@latest supabase-feature-flag --typescript --tailwind --app
cd supabase-feature-flag

Next, install the required dependencies:

npm install @supabase/ssr @supabase/supabase-js @tanstack/react-query

The @supabase/ssr package provides server-side rendering support for Supabase, which is essential for Next.js App Router. @tanstack/react-query provides powerful server state management with automatic caching, invalidation, and real-time updates, which is perfect for feature flags that need to reflect changes immediately without page refreshes.

Database Schema Design

Before writing any code, you need to design your database schema. A feature flag needs several properties:

• A unique key to identify the flag

• A name and description for human readability

• An enabled/disabled state

• Support for user-specific access

• Support for percentage-based rollouts

Here's the SQL migration that creates the feature_flags table:

-- Create feature_flags table
CREATE TABLE IF NOT EXISTS feature_flags (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  key TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  description TEXT,
  enabled BOOLEAN DEFAULT false NOT NULL,
  enabled_for_users JSONB DEFAULT '[]'::jsonb,
  enabled_for_percent INTEGER DEFAULT 0 CHECK (enabled_for_percent >= 0 AND enabled_for_percent <= 100),
  metadata JSONB DEFAULT '{}'::jsonb,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
);

Let's break down each field:

• id: A unique identifier for each flag

• key: A unique string identifier (like "new-dashboard" or "beta-feature")

• name: A human-readable name

• description: Optional description of what the flag controls

• enabled: Global on/off switch

• enabled_for_users: JSON array of user IDs who have access

• enabled_for_percent: Percentage of users who should see the feature (0-100)

• metadata: Flexible JSON field for additional configuration

• created_at and updated_at: Timestamps for tracking

The migration also includes indexes for performance:

-- Create indexes for fast lookups
CREATE INDEX IF NOT EXISTS idx_feature_flags_key ON feature_flags(key);
CREATE INDEX IF NOT EXISTS idx_feature_flags_enabled ON feature_flags(enabled);

Indexes on key and enabled ensure fast queries when checking flag status.

Setting Up Supabase

Step 1: Create a Supabase Project

To start, go to supabase.com and sign up or log in. Then click on "New Project". Fill in your project details and wait for it to initialize.

Step 2: Run the Migration

In your Supabase dashboard, navigate to the SQL Editor:

Then click "New Query". Copy and paste the complete migration SQL (including the indexes and RLS policies shown below) and click "Run".

Here's the complete migration with Row Level Security (RLS) policies:

-- Create feature_flags table
CREATE TABLE IF NOT EXISTS feature_flags (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  key TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  description TEXT,
  enabled BOOLEAN DEFAULT false NOT NULL,
  enabled_for_users JSONB DEFAULT '[]'::jsonb,
  enabled_for_percent INTEGER DEFAULT 0 CHECK (enabled_for_percent >= 0 AND enabled_for_percent <= 100),
  metadata JSONB DEFAULT '{}'::jsonb,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
);

-- Create indexes
CREATE INDEX IF NOT EXISTS idx_feature_flags_key ON feature_flags(key);
CREATE INDEX IF NOT EXISTS idx_feature_flags_enabled ON feature_flags(enabled);

-- Auto-update updated_at timestamp
CREATE OR REPLACE FUNCTION update_updated_at_column()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = NOW();
  RETURN NEW;
END;
$$ language 'plpgsql';

CREATE TRIGGER update_feature_flags_updated_at
  BEFORE UPDATE ON feature_flags
  FOR EACH ROW
  EXECUTE FUNCTION update_updated_at_column();

-- Enable Row Level Security
ALTER TABLE feature_flags ENABLE ROW LEVEL SECURITY;

-- Policy: Allow public read access
CREATE POLICY "Allow public read access"
  ON feature_flags
  FOR SELECT
  USING (true);

-- Policy: Allow public write access (for admin operations)
CREATE POLICY "Allow public write access"
  ON feature_flags
  FOR ALL
  USING (true)
  WITH CHECK (true);

The RLS policies allow:

• Public read access: Anyone can check if a feature flag is enabled

• Public write access: Allows the admin dashboard to create/update flags (in production, you'd restrict this further)

Step 3: Get Your API Credentials

Go to Settings and then API in your Supabase project. Copy your Project URL and Publishable Key. THen create a .env.local file in your project root:

NEXT_PUBLIC_SUPABASE_URL=your_project_url
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=your_publishable_key

Building the Core Feature Flag Logic

Now let's build the core logic for checking feature flags. You'll create separate utilities for client-side and server-side usage.

TypeScript Types

First, define the types you'll use throughout the application:

// types/feature-flag.ts
export interface FeatureFlag {
  id: string;
  key: string;
  name: string;
  description: string | null;
  enabled: boolean;
  enabled_for_users: string[];
  enabled_for_percent: number;
  metadata: Record<string, any>;
  created_at: string;
  updated_at: string;
}

export interface FeatureFlagCheckResult {
  enabled: boolean;
  reason?: string;
}

The FeatureFlag interface matches your database schema. The FeatureFlagCheckResult includes a reason field that explains why a flag is enabled or disabled, which is useful for debugging.

Supabase Client Setup

Create the Supabase client for client-side usage:

// lib/supabase/client.ts
import { createBrowserClient } from "@supabase/ssr";

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY;

export const createClient = () =>
  createBrowserClient(supabaseUrl!, supabaseKey!);

The createBrowserClient function from @supabase/ssr creates a client optimized for browser usage.

For server-side usage:

// lib/supabase/server.ts
import { createServerClient, type CookieOptions } from "@supabase/ssr";
import { cookies } from "next/headers";

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY;

export const createClient = (cookieStore: ReturnType<typeof cookies>) => {
  return createServerClient(
    supabaseUrl!,
    supabaseKey!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll()
        },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            )
          } catch {
            // The `setAll` method was called from a Server Component.
            // This can be ignored if you have middleware refreshing
            // user sessions.
          }
        },
      },
    },
  );
};

This server client handles cookies properly for Next.js server components and API routes.

Client-Side Feature Flag Logic

Create the client-side utility for checking feature flags:

// lib/feature-flags/client.ts
import { createClient } from '@/lib/supabase/client';
import { FeatureFlag, FeatureFlagCheckResult } from '@/types/feature-flag';

// Simple cache with 5 second TTL (React Query handles primary caching)
// This cache is just for reducing redundant calls within a very short window
const cache = new Map<string, { data: FeatureFlag | null; expires: number }>();
const CACHE_TTL = 5000; // 5 seconds - short enough to not interfere with React Query invalidation

function getCached(key: string): FeatureFlag | null | undefined {
  const cached = cache.get(key);
  if (cached && cached.expires > Date.now()) {
    return cached.data;
  }
  return undefined;
}

function setCached(key: string, data: FeatureFlag | null): void {
  cache.set(key, { data, expires: Date.now() + CACHE_TTL });
}

The cache reduces database queries by storing flag data in memory for 5 seconds. This is a secondary cache layer – React Query handles the primary caching and automatic invalidation, ensuring changes reflect immediately across all components.

The getFeatureFlag function fetches a flag from the database:

export async function getFeatureFlag(key: string): Promise<FeatureFlag | null> {
  const cached = getCached(key);
  if (cached !== undefined) return cached;

  const supabase = createClient();
  const { data, error } = await supabase
    .from('feature_flags')
    .select('*')
    .eq('key', key)
    .single();

  if (error) {
    if (error.code === 'PGRST116') {
      setCached(key, null);
      return null;
    }
    console.error('Error fetching feature flag:', error);
    return null;
  }

  setCached(key, data);
  return data;
}

The function first checks the cache. If the flag isn't cached, it queries Supabase. The error code PGRST116 means "not found." In that case, you cache null to avoid repeated queries for non-existent flags.

The core logic is in isFeatureEnabled:

export async function isFeatureEnabled(
  key: string,
  userId?: string
): Promise<FeatureFlagCheckResult> {
  const flag = await getFeatureFlag(key);

  if (!flag) {
    return { enabled: false, reason: 'Flag not found' };
  }

  if (!flag.enabled) {
    return { enabled: false, reason: 'Flag is globally disabled' };
  }

  // Check user-specific access
  if (userId && flag.enabled_for_users.length > 0) {
    if (flag.enabled_for_users.includes(userId)) {
      return { enabled: true, reason: 'User has explicit access' };
    }
    return { enabled: false, reason: 'User not in allowed list' };
  }

  // Check percentage rollout
  if (flag.enabled_for_percent > 0) {
    const hash = simpleHash(userId || key);
    const percentage = hash % 100;
    const enabled = percentage < flag.enabled_for_percent;

    return {
      enabled,
      reason: enabled
        ? `User falls within ${flag.enabled_for_percent}% rollout`
        : `User falls outside ${flag.enabled_for_percent}% rollout`,
    };
  }

  return { enabled: true, reason: 'Flag is globally enabled' };
}

The function follows this logic:

1. Flag doesn't exist: Return disabled

2. Flag is globally disabled: Return disabled

3. User-specific list exists: Check if the user is in the list

4. Percentage rollout is set: Use a hash function to assign users to buckets deterministically

5. Otherwise: Flag is globally enabled

The hash function ensures consistent assignment, so that the same user always gets the same result:

function simpleHash(str: string): number {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    const char = str.charCodeAt(i);
    hash = (hash << 5) - hash + char;
    hash = hash & hash;
  }
  return Math.abs(hash);
}

This creates a deterministic hash, so simpleHash("user-123") always returns the same number, ensuring consistent feature flag decisions.

Server-Side Feature Flag Logic

The server-side version is similar but uses the server Supabase client:

// lib/feature-flags/server.ts
import { createClient } from '@/lib/supabase/server';
import { cookies } from 'next/headers';
import { FeatureFlag, FeatureFlagCheckResult } from '@/types/feature-flag';

export async function getFeatureFlag(key: string): Promise<FeatureFlag | null> {
  const cookieStore = await cookies();
  const supabase = createClient(cookieStore);

  const { data, error } = await supabase
    .from('feature_flags')
    .select('*')
    .eq('key', key)
    .single();

  if (error) {
    if (error.code === 'PGRST116') return null;
    console.error('Error fetching feature flag:', error);
    return null;
  }

  return data;
}

export async function isFeatureEnabled(
  key: string,
  userId?: string
): Promise<FeatureFlagCheckResult> {
  const flag = await getFeatureFlag(key);

  if (!flag) {
    return { enabled: false, reason: 'Flag not found' };
  }

  if (!flag.enabled) {
    return { enabled: false, reason: 'Flag is globally disabled' };
  }

  // Check user-specific access
  if (userId && flag.enabled_for_users.length > 0) {
    if (flag.enabled_for_users.includes(userId)) {
      return { enabled: true, reason: 'User has explicit access' };
    }
    return { enabled: false, reason: 'User not in allowed list' };
  }

  // Check percentage rollout
  if (flag.enabled_for_percent > 0) {
    const hash = simpleHash(userId || key);
    const percentage = hash % 100;
    const enabled = percentage < flag.enabled_for_percent;

    return {
      enabled,
      reason: enabled
        ? `User falls within ${flag.enabled_for_percent}% rollout`
        : `User falls outside ${flag.enabled_for_percent}% rollout`,
    };
  }

  return { enabled: true, reason: 'Flag is globally enabled' };
}

function simpleHash(str: string): number {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    const char = str.charCodeAt(i);
    hash = (hash << 5) - hash + char;
    hash = hash & hash;
  }
  return Math.abs(hash);
}

The logic is identical to the client version, but it uses the server Supabase client that handles cookies correctly.

Setting Up React Query

We’ll rely heavily on React Query throughout this tutorial because feature flags are server-driven values that can change at runtime while users are actively using the application.

React Query provides robust server-state management through caching, background refetching, and cache invalidation. This allows feature flag changes to propagate automatically across the app without forcing page refreshes or manual state synchronization.

Create the Query Provider

First, create the providers/QueryProvider.tsx file to configure and initialize React Query for the entire application:

'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useState } from 'react';

export function QueryProvider({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            // With SSR, we usually want to set some default staleTime
            // above 0 to avoid refetching immediately on the client
            staleTime: 20 * 1000,
            refetchOnWindowFocus: true,
            refetchOnReconnect: true,
          },
        },
      })
  );

  return (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  );
}

What’s happening in this code:

• This file runs on the client because React Query relies on React hooks, which only execute in the browser.

• A single QueryClient instance is created and stored in state so it persists across renders and isn’t recreated.

• The QueryClient defines how server data is cached, when it becomes stale, and when it should be refetched.

This is important because components no longer need to handle fetch logic, loading states, or caching manually. Also, server data is shared and reused across components instead of being refetched repeatedly. And feature flag updates propagate automatically, keeping the app consistent without manual refreshes.

Add Provider to Root Layout

Next, update the app/layout.tsx file to wrap the application with the React Query provider.

import type { Metadata } from 'next'
import './globals.css'
import { QueryProvider } from '@/providers/QueryProvider'

export const metadata: Metadata = {
  title: 'Feature Flag System',
  description: 'Production-ready feature flag system with Next.js and Supabase',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <QueryProvider>{children}</QueryProvider>
      </body>
    </html>
  )
}

We wrap the entire application with QueryProvider, so React Query can manage server data globally across the app.

What QueryProvider actually does

QueryProvider creates and shares a single Query Client that is responsible for:

• Caching data fetched from the server

• Tracking loading and error states

• Automatically refetching data when needed

• Synchronizing data between components

By wrapping the app, every component inside it can use React Query hooks without any extra setup.

Creating the React Hook

Create the hooks/useFeatureFlag.ts file to check whether a feature flag is enabled for a user, using React Query to cache and share the data across components:

'use client';

import { useQuery } from '@tanstack/react-query';
import { isFeatureEnabled } from '@/lib/feature-flags/client';
import { FeatureFlagCheckResult } from '@/types/feature-flag';

export function useFeatureFlag(key: string, userId?: string) {
  const {
    data: result = { enabled: false, reason: 'Loading...' },
    isLoading: loading,
    error,
  } = useQuery<FeatureFlagCheckResult>({
    queryKey: ['featureFlag', key, userId],
    queryFn: () => isFeatureEnabled(key, userId),
    staleTime: 30 * 1000,
    refetchOnWindowFocus: true,
  });

  return { ...result, loading, error };
}

What’s happening in the code:

• 'use client'; ensures this file runs in the browser because React Query hooks can only run on the client.

• useQuery fetches the feature flag status from the server and caches the result.

• queryKey: ['featureFlag', key, userId] uniquely identifies this query so React Query can cache it separately for each feature and user.

• queryFn: () => isFeatureEnabled(key, userId) is the function that actually checks if the feature is enabled.

• staleTime: 30 * 1000 keeps the cached data fresh for 30 seconds before refetching.

• refetchOnWindowFocus: true automatically refetches the data when the user switches back to the tab.

• return { ...result, loading, error } makes it easy for components to access the flag status, loading state, and any errors.

Admin Hooks for Managing Flags

We’re going to create a set of React Query hooks to manage feature flags from the admin dashboard. These hooks allow you to fetch, create, update, and delete feature flags while automatically keeping your UI in sync.

Step 1: Create the hooks file

Start by creating a new file at hooks/useFeatureFlags.ts file. This is where we’ll implement all the hooks for the admin to manage feature flags.

After creating the hooks/useFeatureFlags.ts file, import React Query hooks and the FeatureFlag type so we can fetch, update, create, and delete feature flags with type safety and caching.

'use client';

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { FeatureFlag } from '@/types/feature-flag';

In this code:

• useQuery fetches and caches server data automatically.

• useMutation sends updates, creates, or deletes data on the server.

• useQueryClient gives access to the query cache so we can invalidate or update queries after mutations.

• FeatureFlag is the TypeScript type definition for feature flags, ensuring our hooks use correct data structures.

Step 2: Add a hook to fetch all feature flags

Next, in the same hooks/useFeatureFlags.ts file, add a hook to fetch all feature flags for the admin page. This hook will allow components to retrieve the list of flags and automatically cache the data using React Query.

export function useFeatureFlags() {
  return useQuery<FeatureFlag[]>({
    queryKey: ['featureFlags'],
    queryFn: async () => {
      const response = await fetch('/api/feature-flags');
      const { data } = await response.json();
      return data || [];
    },
    staleTime: 30 * 1000,
  });
}

What’s happening in the code:

• useQuery fetches all feature flags from the server and caches them automatically.

• queryKey: ['featureFlags'] uniquely identifies this query so React Query can manage caching and refetching.

• queryFn is an async function that calls the /api/feature-flags endpoint and returns the data.

• staleTime: 30 * 1000 keeps the cached data fresh for 30 seconds before refetching.

This matters because admin components always display the latest flags without manual refresh. Also, cached data reduces unnecessary network requests. Finally, any component using this hook will automatically update when the flags change.

Step 3: Add a hook to update a feature flag

Next, in the same hooks/useFeatureFlags.ts file, add a hook to update an existing feature flag. This hook will allow the admin to modify a flag and ensure all components using it get the updated value automatically.

export function useUpdateFeatureFlag() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async ({
      key,
      updates,
    }: {
      key: string;
      updates: Partial<FeatureFlag>;
    }) => {
      const response = await fetch(`/api/feature-flags/${key}`, {
        method: 'PATCH',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updates),
      });

      if (!response.ok) {
        throw new Error('Failed to update feature flag');
      }

      const { data } = await response.json();
      return data;
    },
    onSuccess: (data, variables) => {
      // Invalidate and refetch feature flags list
      queryClient.invalidateQueries({ queryKey: ['featureFlags'] });
      // Invalidate the specific feature flag check
      queryClient.invalidateQueries({
        queryKey: ['featureFlag', variables.key],
      });
      // Invalidate all feature flag checks (in case userId was involved)
      queryClient.invalidateQueries({ queryKey: ['featureFlag'] });
    },
  });
}

What’s happening in the code:

• useMutation creates a function to update a feature flag on the server.

• mutationFn is an async function that sends a PATCH request to /api/feature-flags/${key} with the updated data.

• onSuccess runs after a successful update to invalidate cached queries so the latest data is available everywhere:

  • ['featureFlags'] updates the full list of flags.

  • ['featureFlag', variables.key] updates the specific flag that was changed.

  • ['featureFlag'] updates any other cached flag checks (for example, per user checks).

Step 4: Add a hook to delete a feature flag

Next, add the useDeleteFeatureFlag hook to delete a feature flag. This hook allows the admin to remove a flag from the system and ensures the UI updates automatically everywhere the flag was used.

export function useDeleteFeatureFlag() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (key: string) => {
      const response = await fetch(`/api/feature-flags/${key}`, {
        method: 'DELETE',
      });

      if (!response.ok) {
        throw new Error('Failed to delete feature flag');
      }
    },
    onSuccess: (_, key) => {
      // Invalidate and refetch feature flags list
      queryClient.invalidateQueries({ queryKey: ['featureFlags'] });
      // Invalidate the specific feature flag check
      queryClient.invalidateQueries({ queryKey: ['featureFlag', key] });
    },
  });
}

What’s happening in the code:

• useMutation creates a function to delete a feature flag from the server.

• mutationFn is an async function that sends a DELETE request to /api/feature-flags/${key}.

• onSuccess runs after the flag is successfully deleted to invalidate the cache so the UI updates:

  • ['featureFlags'] refetches the full list of flags.

  • ['featureFlag', key] removes the deleted flag from any cached queries.

Step 5: Add a hook to create a new feature flag

Finally, add the useCreateFeatureFlag hook to create a new feature flag. This allows the admin to add new flags and ensures the dashboard updates automatically when a new flag is created.

export function useCreateFeatureFlag() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (flag: {
      key: string;
      name: string;
      description?: string;
      enabled?: boolean;
      enabled_for_users?: string[];
      enabled_for_percent?: number;
      metadata?: Record<string, any>;
    }) => {
      const response = await fetch('/api/feature-flags', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(flag),
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.error || 'Failed to create feature flag');
      }

      const { data } = await response.json();
      return data;
    },
    onSuccess: () => {
      // Invalidate and refetch feature flags list
      queryClient.invalidateQueries({ queryKey: ['featureFlags'] });
    },
  });
}

What’s happening in the code:

• useMutation creates a function to send a new feature flag to the server.

• mutationFn is an async function that posts the flag data to /api/feature-flags.

• onSuccess runs after a successful creation to invalidate the cached list of flags, so the admin dashboard shows the new flag immediately.

Feature Flag Gate Component

Now we’ll create a wrapper component to conditionally render UI based on feature flags. This helps you show or hide parts of your app depending on whether a flag is enabled for a user.

Create the components/FeatureFlagGate.tsx file and add the following code:

'use client';

import { ReactNode } from 'react';
import { useFeatureFlag } from '@/hooks/useFeatureFlag';

interface FeatureFlagGateProps {
  flagKey: string;
  userId?: string;
  children: ReactNode;
  fallback?: ReactNode;
  showLoading?: ReactNode;
}

export function FeatureFlagGate({
  flagKey,
  userId,
  children,
  fallback = null,
  showLoading = null,
}: FeatureFlagGateProps) {
  const { enabled, loading } = useFeatureFlag(flagKey, userId);

  if (loading && showLoading !== null) {
    return <>{showLoading}</>;
  }

  if (!enabled) {
    return <>{fallback}</>;
  }

  return <>{children}</>;
}

What’s happening in the code:

• useFeatureFlag(flagKey, userId) checks whether the feature is enabled for a specific user and tracks loading state.

• loading && showLoading !== null: if the data is still loading, render the optional showLoading UI.

• !enabled: if the feature is disabled, render the optional fallback UI.

• children renders the actual content only if the flag is enabled and not loading.

This makes it easy to conditionally render features without scattering logic throughout your components. It also supports custom loading and fallback UI for better user experience. And it works with React Query caching automatically, so flag changes propagate immediately.

Building the Admin Dashboard

Admins need a way to manage feature flags in your app. To do this, we’ll create API routes that support CRUD operations (Create, Read, Update, Delete). These routes will interact with Supabase to store and modify flag data.

Step 1: Create the main feature flags API route

Start by creating the app/api/feature-flags/route.ts file. This file will handle fetching all feature flags (GET) and creating new ones (POST).

import { NextRequest, NextResponse } from 'next/server';
import { createClient } from '@/lib/supabase/server';
import { cookies } from 'next/headers';

export async function GET(request: NextRequest) {
  try {
    const cookieStore = await cookies();
    const supabase = createClient(cookieStore);
    const { data, error } = await supabase
      .from('feature_flags')
      .select('*')
      .order('created_at', { ascending: false });

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ data });
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

export async function POST(request: NextRequest) {
  try {
    const cookieStore = await cookies();
    const supabase = createClient(cookieStore);
    const body = await request.json();

    if (!body.key || !body.name) {
      return NextResponse.json(
        { error: 'key and name are required' },
        { status: 400 }
      );
    }

    const { data, error } = await supabase
      .from('feature_flags')
      .insert({
        key: body.key,
        name: body.name,
        description: body.description || null,
        enabled: body.enabled || false,
        enabled_for_users: body.enabled_for_users || [],
        enabled_for_percent: body.enabled_for_percent || 0,
        metadata: body.metadata || {},
      })
      .select()
      .single();

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ data }, { status: 201 });
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

What’s happening in this file:

• GET fetches all feature flags from Supabase, ordered by creation date.

• POST creates a new feature flag in Supabase. It checks that key and name exist, and sets defaults for optional fields.

• createClient(cookieStore) authenticates requests with Supabase using cookies from the client.

• NextResponse.json() sends JSON responses with data or error messages.

Step 2: Create the dynamic route for individual flags

Next, Create the file app/api/feature-flags/[key]/route.ts. This route handles updating (PATCH) and deleting (DELETE) individual flags based on their key.

import { NextRequest, NextResponse } from 'next/server';
import { createClient } from '@/lib/supabase/server';
import { cookies } from 'next/headers';

export async function PATCH(
  request: NextRequest,
  { params }: { params: { key: string } }
) {
  try {
    const cookieStore = await cookies();
    const supabase = createClient(cookieStore);
    const body = await request.json();

    const { data, error } = await supabase
      .from('feature_flags')
      .update({
        ...(body.name !== undefined && { name: body.name }),
        ...(body.description !== undefined && { description: body.description }),
        ...(body.enabled !== undefined && { enabled: body.enabled }),
        ...(body.enabled_for_users !== undefined && {
          enabled_for_users: body.enabled_for_users,
        }),
        ...(body.enabled_for_percent !== undefined && {
          enabled_for_percent: body.enabled_for_percent,
        }),
      })
      .eq('key', params.key)
      .select()
      .single();

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ data });
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

export async function DELETE(
  request: NextRequest,
  { params }: { params: { key: string } }
) {
  try {
    const cookieStore = await cookies();
    const supabase = createClient(cookieStore);

    const { error } = await supabase
      .from('feature_flags')
      .delete()
      .eq('key', params.key);

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ success: true });
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

What’s happening in this file:

• PATCH updates a feature flag with only the fields provided in the request body.

  • Uses the spread operator (...) to include only fields that exist.

• DELETE removes the feature flag identified by key.

• eq('key', params.key) ensures the operation targets the correct flag.

Step 3: Create the Admin Dashboard UI

Now, create the file app/admin/page.tsx. This is the main admin dashboard where you can view, create, and manage feature flags.

With React Query, the admin dashboard becomes much cleaner and automatically updates when flags change:

'use client';

import { useState } from 'react';
import { FeatureFlagList } from '@/components/admin/FeatureFlagList';
import { CreateFeatureFlagModal } from '@/components/admin/CreateFeatureFlagModal';
import { useFeatureFlags } from '@/hooks/useFeatureFlags';

export default function AdminPage() {
  const [showCreateModal, setShowCreateModal] = useState(false);
  const { data: flags = [], isLoading: loading } = useFeatureFlags();

  return (
    <div className='min-h-screen bg-gray-50 py-8'>
      <div className='max-w-7xl mx-auto px-4 sm:px-6 lg:px-8'>
        <div className='mb-8 flex justify-between items-center'>
          <div>
            <h1 className='text-3xl font-bold text-gray-900'>
              Feature Flags Admin
            </h1>
            <p className='mt-2 text-sm text-gray-600'>
              Manage your feature flags and rollouts
            </p>
          </div>
          <button
            onClick={() => setShowCreateModal(true)}
            className='px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition-colors'
          >
            Create Feature Flag
          </button>
        </div>

        {loading ? (
          <div className='text-center py-12'>
            <div className='inline-block animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600'></div>
            <p className='mt-4 text-gray-600'>Loading feature flags...</p>
          </div>
        ) : (
          <FeatureFlagList flags={flags} />
        )}

        {showCreateModal && (
          <CreateFeatureFlagModal
            onClose={() => setShowCreateModal(false)}
            onSuccess={() => {
              setShowCreateModal(false);
            }}
          />
        )}
      </div>
    </div>
  );
}

What’s happening in this file:

• 'use client'; marks this page as a client component so hooks like useState and React Query can run.

• useState manages whether the “Create Feature Flag” modal is open or closed.

• useFeatureFlags() fetches all feature flags from the API and keeps the list in sync automatically.

• const { data: flags = [], isLoading: loading } :

  • flags contains the feature flag list

  • loading tracks whether the data is still being fetched

• loading ? ... : <FeatureFlagList /> :

  • Shows a loading spinner while flags are being fetched

  • Renders the feature flag table once data is available

• FeatureFlagList displays all feature flags and their current states.

Using Feature Flags Mutations in Components

Earlier, we created mutation hooks for creating, updating, and deleting feature flags. Now let’s see how those hooks are actually used inside UI components to trigger updates and keep the interface in sync.

Here's how to use the mutation hooks in your components:

'use client'

import { useState } from 'react'
import { FeatureFlag } from '@/types/feature-flag'
import { EditFeatureFlagModal } from './EditFeatureFlagModal'
import {
  useUpdateFeatureFlag,
  useDeleteFeatureFlag,
} from '@/hooks/useFeatureFlags'

interface FeatureFlagCardProps {
  flag: FeatureFlag
}

export function FeatureFlagCard({ flag }: FeatureFlagCardProps) {
  const [isEditing, setIsEditing] = useState(false)
  const updateFlag = useUpdateFeatureFlag()
  const deleteFlag = useDeleteFeatureFlag()

  const handleToggle = async () => {
    try {
      await updateFlag.mutateAsync({
        key: flag.key,
        updates: { enabled: !flag.enabled },
      })
    } catch (error) {
      console.error('Error toggling flag:', error)
      alert('Failed to toggle feature flag')
    }
  }

  const handleDelete = async () => {
    if (!confirm(`Are you sure you want to delete "${flag.name}"?`)) {
      return
    }

    try {
      await deleteFlag.mutateAsync(flag.key)
    } catch (error) {
      console.error('Error deleting flag:', error)
      alert('Failed to delete feature flag')
    }
  }

  return (
    <>
      <div className="bg-white rounded-lg shadow p-6">
        <div className="flex items-start justify-between">
          <div className="flex-1">
            <div className="flex items-center gap-3">
              <h3 className="text-lg font-semibold text-gray-900">
                {flag.name}
              </h3>
              <span
                className={`px-2 py-1 text-xs font-medium rounded-full ${
                  flag.enabled
                    ? 'bg-green-100 text-green-800'
                    : 'bg-gray-100 text-gray-800'
                }`}
              >
                {flag.enabled ? 'Enabled' : 'Disabled'}
              </span>
            </div>
            <p className="mt-1 text-sm text-gray-600 font-mono">{flag.key}</p>
            {flag.description && (
              <p className="mt-2 text-sm text-gray-500">{flag.description}</p>
            )}

            <div className="mt-4 flex flex-wrap gap-4 text-sm text-gray-600">
              {flag.enabled_for_users.length > 0 && (
                <div>
                  <span className="font-medium">Users:</span>{' '}
                  {flag.enabled_for_users.length} user(s)
                </div>
              )}
              {flag.enabled_for_percent > 0 && (
                <div>
                  <span className="font-medium">Rollout:</span>{' '}
                  {flag.enabled_for_percent}%
                </div>
              )}
            </div>
          </div>

          <div className="flex items-center gap-2 ml-4">
            <button
              onClick={handleToggle}
              disabled={updateFlag.isPending}
              className={`px-3 py-1.5 text-sm font-medium rounded transition-colors ${
                flag.enabled
                  ? 'bg-red-100 text-red-700 hover:bg-red-200'
                  : 'bg-green-100 text-green-700 hover:bg-green-200'
              } disabled:opacity-50`}
            >
              {updateFlag.isPending
                ? '...'
                : flag.enabled
                ? 'Disable'
                : 'Enable'}
            </button>
            <button
              onClick={() => setIsEditing(true)}
              className="px-3 py-1.5 text-sm font-medium text-blue-700 bg-blue-100 rounded hover:bg-blue-200 transition-colors"
            >
              Edit
            </button>
            <button
              onClick={handleDelete}
              className="px-3 py-1.5 text-sm font-medium text-red-700 bg-red-100 rounded hover:bg-red-200 transition-colors"
            >
              Delete
            </button>
          </div>
        </div>
      </div>

      {isEditing && (
        <EditFeatureFlagModal
          flag={flag}
          onClose={() => setIsEditing(false)}
          onSuccess={() => {
            setIsEditing(false)
          }}
        />
      )}
    </>
  )
}

The component above works without any manual refetching or state synchronization logic. The moment a mutation succeeds, React Query automatically updates or invalidates the relevant cached data. That behavior is what enables the smooth, real-time updates you see in the UI.

Because all feature flag data is managed by React Query:

• When a flag is toggled, React Query automatically invalidates the relevant queries

• Any component using that flag immediately receives the updated value

• The admin dashboard stays in sync with the rest of the application without extra code

• Loading and error states are handled consistently across all mutations.

Implementing a Real-World Example

To make all of this concrete, let’s walk through a real-world example.

In this section, we’ll build a simple Todo feature that is entirely controlled by a feature flag. When the flag is disabled, users see a message explaining that the feature isn’t available. When it’s enabled, the full Todo interface appears instantly without redeploying or refreshing the page.

This demonstrates how feature flags can safely gate entire pages or features in a live application.

Below is what the experience looks like as the feature flag is toggled on and off from the admin dashboard:

Step 1: Create the Todo Page File

Create a new file app/todos/page.tsx. This page shows how to use a feature flag to conditionally render a full component. Let's build a todo app that's controlled by a feature flag. This demonstrates real-world usage.

At the top of the file, import the hooks we need and define the Todo interface.

'use client';

import { useState, useEffect } from 'react';
import { FeatureFlagGate } from '@/components/FeatureFlagGate';

interface Todo {
  id: string;
  text: string;
  completed: boolean;
}

Step 2: Initialize state in the component

Create the component and define state for todos and the input:

export default function TodosPage() {
  const [todos, setTodos] = useState<Todo[]>([]);
  const [inputValue, setInputValue] = useState('');

Here’s what’s going on:

• todos stores all todo items.

• inputValue tracks what the user types in the input field.

Step 3: Load and save todos from localStorage

  useEffect(() => {
    const saved = localStorage.getItem('todos');
    if (saved) setTodos(JSON.parse(saved));
  }, []);

  useEffect(() => {
    localStorage.setItem('todos', JSON.stringify(todos));
  }, [todos]);

In this code, the first useEffect loads saved todos from the browser’s localStorage when the component mounts. The second useEffect saves todos whenever the list changes. This ensures your todos persist across page reloads.

Step 4: Add helper functions

  const addTodo = () => {
    if (inputValue.trim()) {
      setTodos([...todos, { 
        id: Date.now().toString(), 
        text: inputValue.trim(), 
        completed: false 
      }]);
      setInputValue('');
    }
  };

  const toggleTodo = (id: string) => {
    setTodos(todos.map(todo => 
      todo.id === id ? { ...todo, completed: !todo.completed } : todo
    ));
  };

  const deleteTodo = (id: string) => {
    setTodos(todos.filter(todo => todo.id !== id));
  };

In this code,

• addTodo adds a new todo item with a unique id and resets the input.

• toggleTodo marks a todo as completed or incomplete.

• deleteTodo removes a todo from the list.

Step 5: Render the Todo App inside the FeatureFlagGate

  return (
    <div className="max-w-2xl mx-auto p-8">
      <h1 className="text-4xl font-bold mb-6">Todo App</h1>

      <FeatureFlagGate
        flagKey="test"
        fallback={
          <div className="bg-yellow-50 border-2 border-yellow-200 rounded-lg p-6">
            <h3 className="font-semibold mb-2">Feature Not Available</h3>
            <p>Enable the "test" feature flag in the admin dashboard.</p>
          </div>
        }
      >

What’s going on here:

• We wrap the Todo app in FeatureFlagGate.

• flagKey="test" only shows the Todo app if this feature flag is enabled.

• fallback displays a message when the feature is disabled.

Step 6: Add the input field and Add button

        <div className="mb-6">
          <div className="flex gap-2">
            <input
              type="text"
              value={inputValue}
              onChange={(e) => setInputValue(e.target.value)}
              onKeyPress={(e) => e.key === 'Enter' && addTodo()}
              placeholder="What needs to be done?"
              className="flex-1 px-4 py-3 border rounded-lg"
            />
            <button
              onClick={addTodo}
              className="px-6 py-3 bg-purple-600 text-white rounded-lg"
            >
              Add
            </button>
          </div>
        </div>

In this code,

• Input field captures new todo text.

• Pressing Enter or clicking Add triggers addTodo.

• It’s styled with Tailwind CSS for spacing and rounded borders.

Step 8: Display the list of todos

        <div className="space-y-2">
          {todos.map((todo) => (
            <div
              key={todo.id}
              className="flex items-center gap-3 p-4 bg-gray-50 rounded-lg"
            >
              <button
                onClick={() => toggleTodo(todo.id)}
                className={`w-6 h-6 rounded-full border-2 ${
                  todo.completed
                    ? 'bg-green-500 border-green-500'
                    : 'border-gray-300'
                }`}
              >
                {todo.completed && '✓'}
              </button>
              <span className={todo.completed ? 'line-through' : ''}>
                {todo.text}
              </span>
              <button
                onClick={() => deleteTodo(todo.id)}
                className="text-red-500"
              >
                Delete
              </button>
            </div>
          ))}
        </div>
      </FeatureFlagGate>
    </div>
  );
}

This code,

• Loops over todos to display each item.

• Shows a toggle button to mark as complete, a delete button, and the todo text.

• Completed todos get a line-through style.

• All interaction happens inside the FeatureFlagGate, so users only see this when the flag is enabled.
  The entire todo app is wrapped in FeatureFlagGate. When the "test" flag is disabled, users see a message instead of the app. When enabled, they see the full todo interface.

Todo App Overview

This Todo app demonstrates how feature flags work in a live application. It shows how admins can enable or disable the "test" feature flag dynamically from the dashboard.

FeatureFlagGate ensures the interface updates immediately when the flag changes, and entire components or pages can be toggled on or off safely using feature flags.

Server-Side Usage

Feature flags shouldn’t only live on the client. In many cases, you’ll want to enforce them on the server as well, especially for APIs, background jobs, or sensitive business logic.

In this example, we’ll protect an API route by checking a feature flag on the server before returning any data.

First, create the API route file app/api/some-feature/route.ts. This demonstrates how to check a feature flag on the server before returning data.

import { isFeatureEnabled } from '@/lib/feature-flags/server';
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  const userId = request.headers.get('user-id') || undefined;
  const result = await isFeatureEnabled('new-feature', userId);

  if (!result.enabled) {
    return NextResponse.json(
      { error: 'Feature not available' },
      { status: 403 }
    );
  }

  // Feature is enabled, proceed with logic
  return NextResponse.json({ data: 'Feature content' });
}

What’s happening in this file:

• File creation: app/api/some-feature/route.ts defines a new API route.

• isFeatureEnabled: Checks whether the 'new-feature' flag is active for the user.

• Conditional response: Returns a 403 error if the feature is disabled. Otherwise, proceeds normally.

• Server-side gating: Lets you protect entire endpoints, so users only access functionality when the feature is enabled.

Why React Query?

Feature flags introduce a unique challenge because they must remain consistent across the entire UI even as they change dynamically. Without a dedicated server-state solution, you’d need to manually refetch data, coordinate updates between components, and handle edge cases where parts of the UI fall out of sync.

React Query treats feature flags as shared server state. Once fetched, flags are cached and reused across components. When an admin updates a flag, the cache is invalidated and refetched in the background, triggering immediate UI updates everywhere the flag is used. This makes React Query a natural fit for feature flags, where correctness, consistency, and real-time updates are critical.

Real-World Impact

Before React Query:

// Had to manually refetch after every update
const handleToggle = async () => {
  await fetch(`/api/feature-flags/${key}`, { method: 'PATCH', ... });
  fetchFlags(); // Manual refetch
  // Other components still show old data until page refresh
};

After React Query:

// Automatic cache invalidation - everything updates instantly
const updateFlag = useUpdateFeatureFlag();
await updateFlag.mutateAsync({ key, updates });
// All components using this flag automatically update!

Conclusion

You’ve now built a complete, production-ready feature flag system using Next.js and Supabase. The system supports global toggles, user-specific access, and percentage-based rollouts, all backed by a flexible database schema.

Feature flags can be checked on both the client and the server, ensuring consistent behavior across UI components and API routes. With React Query handling caching and invalidation, changes made in the admin dashboard propagate instantly throughout the application without deploying or refreshing the page.

Feature flags are a foundational tool for modern development. They let you deploy code safely, test new ideas with real users, and react quickly when something goes wrong. With this setup in place, you can confidently extend the system with audit logs, analytics, scheduled rollouts, or deeper CI/CD integrations as your product grows.

Caching is great for performance, but it becomes a pain when you don’t realize which layer is reusing old data.

If you’ve ever seen this:

• You update a profile name, but the screen still shows the old one.

• You delete an item, but it stays in the list.

• Your API returns fresh JSON, but the page refuses to change.

• You deploy a fix, but your teammate still sees the old behavior.

You’re probably hitting a cache.

What makes this especially confusing is that not all stale UI comes from “real” caches. Modern web apps have multiple places where data can be reused, saved, or replayed between your UI, your API and when your app is deployed. When you don’t have a clear mental model of these layers, debugging turns into guesswork.

This article lays out a practical guide of the five most common caching layers that cause stale UI, plus one non-cache trap that looks exactly like one. The goal is to help you quickly identify where stale data is coming from, so you can fix the right thing instead of “refreshing harder.”

Why it Matters

I first ran into this while building an app where the UI wouldn’t update after a successful change. The API returned 200 OK, the database was correct, but the screen stayed stale. I assumed something was wrong with my code or state logic. Instead, the issue was coming from a caching layer I hadn’t invalidated. That’s the real problem with stale UI, you can’t debug it effectively unless you know which layer might be serving cached data.

When you understand where caching happens:

• You debug faster by identifying the layer instead of guessing.

• You avoid production-only bugs caused by caching defaults.

• You stop chasing React issues when the data was never fresh.

This article gives you a simple mental model to pinpoint the layer and fix the right thing.

Table of Contents

• Why it Matters

• The Mental Model

• Non-Cache Cause

• Cache 1: React Query Cache

• Cache 2: Next.js fetch() Caching

• Cache 3: Browser HTTP Cache (a Saved Copy in Your Browser)

• Cache 4: CDN/Hosting Cache

• Cache 5: Service Worker Cache (Only if Your Site is a PWA)

• 10-Second Debug Guide

• Prevention: Set Caching Intentionally

• Recap

The Mental Model

When your UI shows data, it feels like it comes straight from your API. In reality, the request/response path can hit multiple reuse points.

Non-Cache Cause

Duplicated React local state (same symptoms as caching). This one isn’t a formal cache, but it causes a lot of “why didn’t it update?” bugs especially for beginners.

The common trap:

const [name, setName] = useState(user.name) // initialized once

useState only uses its argument during the initial render. On every subsequent render, React ignores this value and preserves the existing state.

If user.name later changes (for example, after fresh API data arrives), the name state will not update automatically. At that point, name becomes a stale copy of user.name, and the UI renders outdated data unless you manually synchronize it.

This happens because you have duplicated state:

• user.name is the source of truth.

• name state is a local snapshot taken once.

React does not keep duplicated state in sync for you.

Correct patterns:

1. Render directly from the source when possible.

If the value is not being edited locally, do not copy it into state:

<span>{user.name}</span>

This guarantees the UI always reflects the latest data.

2. Explicitly synchronize local state when editable state is required.

If you need local, editable state (for example, a controlled input), you must opt in to synchronization:

const [name, setName] = useState(user.name);  

    useEffect(() => {    
        setName(user.name); 
     }, [user.name]);

This effect runs only when user.name changes, explicitly updating local state to match the new source value.

Cache 1: React Query Cache

React Query (TanStack Query) stores query results in a QueryClient cache (in memory by default) so your UI can render quickly and avoid unnecessary network requests. When a component needs data, React Query can return cached data immediately and then decide whether to fetch the data again based on options like staleTime and “refetch” behaviors (on mount, window focus, reconnect).

Common failure mode: mutation succeeds, but the UI stays old

A 200 OK only confirms the mutation request succeeded. It does not automatically update the cached query data your UI is rendering.

After a mutation, one of these usually happens:

• The query that renders the screen was not invalidated/fetched

• You invalidated the wrong query key (the UI reads from a different key)

• The UI is rendering local React state that’s out of sync (not the query result)

The simplest “safe” pattern is: invalidate the exact query key your UI uses, so it fetches fresh data.

import { useMutation, useQueryClient } from "@tanstack/react-query";

function useUpdateProfile(userId: string) {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: updateProfileRequest,
    onSuccess: () => {
      // Invalidate the same key your UI query uses (example: ["user", userId])
      queryClient.invalidateQueries({ queryKey: ["user", userId] });
    },
  });
}

If your UI uses a different key (for example ["me"] or ["user", userId, "profile"]), you must invalidate that key instead, React Query won’t “figure it out” from the URL.

Query Keys: React Query Caches by Key, not URL

React Query does not cache by endpoint URL. The query key is the identity of the cached data. If two different requests share the same key, React Query treats them as the same data and they can overwrite each other.

You should avoid keys like ["user"] (too broad), and use keys like ["user", userId] and ["users", { page, search, filter }].

Two settings that control “when it will refetch”:

• staleTime: how long cached data is treated as fresh. While data is fresh, React Query is less likely to refetch automatically.

• gcTime (formerly cacheTime): how long unused query data stays in memory after it’s no longer used by any component, before it’s garbage collected.

Cache 2: Next.js fetch() Caching

This is the one that surprises a lot of frontend devs. Next.js can cache results to speed things up. That means your server might return a previously saved copy of:

• The API data it fetched, or

• The page it already built

This is often the first time frontend developers encounter server-side caching behavior that affects UI correctness. So, even if your database has the new value, you can still see the old one, because Next.js didn’t fetch the API again, or didn’t rebuild the page this time.

This mainly applies to the App Router (Next.js calls these saved copies the Data Cache and Full Route Cache).

What you’ll notice when this happens

• You refresh the page and it still shows the old value.

• Your API is correct (Postman/curl shows the new email), but the UI is stuck.

• Sometimes it “fixes itself” after a short wait (because the saved copy refreshes on a timer).

For example: “I updated my profile email, but prod still shows the old one”

The page (reads email on the server):

// app/settings/page.tsx
export default async function SettingsPage() {
 const res = await fetch("https://api.example.com/users/42", {
  method: "GET",
})
  const user = await res.json();

  return (
    <main>
      <h1>Settings</h1>
      <p>Email: {user.email}</p>
    </main>
  );
}

You submit an “Update email” form, the API returns 200 OK, the database is updated, but /settings still shows the previous email in production.

That usually means you’re seeing a saved copy somewhere on the server side.

How to debug it

Step 1: Reproduce in a production-like run

Caching can behave differently in development. Run:

next build && next start

Then test again.

Step 2: Confirm whether the request is reaching your Next.js server at all

Add a log inside the page:

console.log("Rendering /settings at", new Date().toISOString());

Then reload settings twice.

• If you see a new timestamp every reload, the request is reaching your server and the page code is running.

• If you don’t see logs in production, your request may not be reaching your server at all (often because a hosting/CDN layer is serving a saved copy before Next.js runs). You’ll confirm that in the CDN section later.

Step 3: Force Next.js to ask your API every time

Change the fetch to:

const res = await fetch("https://api.example.com/me", {
  method: "GET",
  cache: "no-store",
});

This means: don’t save this response – always fetch it again.

If this fixes the stale email then the problem was a saved copy of the API response (Data Cache).

Step 4: If the email is still stale, force Next.js to rebuild the page every request

Add this to the page file:

// app/settings/page.tsx
export const dynamic = "force-dynamic";

This means: don’t serve a saved copy of the page; rebuild it per request.

A “beginner-safe” setup for the user settings pages with some of the suggestions:

// app/settings/page.tsx
export const dynamic = "force-dynamic";

export default async function SettingsPage() {
  const res = await fetch("https://api.example.com/me", { cache: "no-store" });
  const me = await res.json();
  return <p>Email: {me.email}</p>;
}

When you want caching for speed, but still need real time updates, these are some options you can take:

Option A: Refresh the saved copy every N seconds

Good for public pages, not ideal for “my settings must update now.”

await fetch(url, { next: { revalidate: 60 } });

This means: “You can reuse a saved copy, but refresh it at most every 60 seconds.”

Option B: Refresh right after the update (best for “update email” flows)

If you update the email on the server (Server Action or API route), tell Next.js to throw away the saved copy for /settings page so the next visit is fresh:

// app/settings/actions.ts
"use server";

import { revalidatePath } from "next/cache";

export async function updateEmail(email: string) {
  await fetch("https://api.example.com/me/email", {
    method: "PUT",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ email }),
  });

  // Tell Next.js: next request to /settings should be rebuilt
  revalidatePath("/settings");
}

Note: Next.js caching details can differ by version and by App Router vs Pages Router. Instead of trying to memorize defaults, debug by setting the behavior explicitly (no-store, revalidate, force-dynamic) and observe what changes.

Cache 3: Browser HTTP Cache (a Saved Copy in Your Browser)

Sometimes the browser reuses a saved copy of an API response (from memory or disk), so it doesn’t fully fetch it again.

What you’ll notice

You open DevTools, and the network shows (from memory cache) or (from disk cache).

Fast check

DevTools → Network

• Turn on Disable cache (only works while DevTools is open)

• Reload and retry

Why it happens

Usually your server allows caching via headers like Cache-Control or ETag (which can lead to 304 Not Modified).

Cache 4: CDN/Hosting Cache

This is often a production-only cache, which is why frontend bugs can appear “impossible” to reproduce locally. In production, a CDN/hosting layer can serve a saved copy of a response before your request reaches your server. That’s why “prod is stale, local is fine” happens.

What you’ll notice

• Prod is stale, local is fine

• Different users see different results (different regions/POPs)

• Pages are very fast even right after data changed

Fast check

Open DevTools → Network → click the request → Response Headers

• Age: if present and increasing, it’s strong evidence you’re getting a cached response from an intermediary cache

• Provider headers can hint HIT/MISS (examples: x-vercel-cache, cf-cache-status)

• Source (Age header, HTTP caching): https://www.rfc-editor.org/rfc/rfc9111

Quick diagnostic check

Change the URL slightly by adding this to the end of the URL:

?debug=1700000000000

If the new URL shows fresh data, the edge was likely caching the original URL. This doesn’t fix it for everyone, you’d still need correct cache settings or a purge/invalidation on your CDN.

Cache 5: Service Worker Cache (Only if Your Site is a PWA)

If your site has a service worker, it can return a saved response before the network runs. This can make new deployments or new data seem “ignored.”

What you’ll notice

• Works in Incognito but not normal mode

• Hard refresh doesn’t help

• DevTools “Disable cache” doesn’t fully explain it

Fast check (Chrome)

Open DevTools → Application → Service Workers

• enable Bypass for network, or Unregister temporarily

• reload and retest

10-Second Debug Guide

Stale data is rarely random: it usually means a cache layer is doing its job, just not in the way you expect. Modern applications stack multiple caches, so debugging is less about fixing code immediately and more about locating the layer responsible.

Think of this as a quick cheat sheet to figure out which cache layer might be serving stale data, so you can focus your debugging on the right layer.

• No request in Network? Go to Cache 1 (React Query), then Local state, then Cache 5 (Service worker).

• Request exists, but response is old? Go to Cache 3 (Browser), Cache 4 (CDN), then Cache 2 (Next.js).

• Response is fresh, UI is old? Go back to Cache 1 (invalidating / query keys) and Local state.

Once you know the likely layer, use the Fast check in that section to confirm it.

Prevention: Set Caching Intentionally

Most stale-data bugs happen because caching settings were never chosen but the defaults were.

• User-specific pages (settings/admin/dashboard): default to fresh: Next.js: use cache: "no-store" on important fetches, and/or force dynamic routes when needed.

• Public pages (marketing/blog/docs): saving + revalidate is usually fine: Decide a revalidate window that matches the business need (seconds/minutes/hours).

• React Query: set staleTime based on how often the data actually changes, and make query keys match the inputs.

• APIs: set Cache-Control / Vary intentionally so shared caches don’t mix user-specific responses.

Recap

Caching itself isn’t the problem. Stale UI happens when a cache exists but you didn’t choose it intentionally or align it with the data’s freshness requirements.

If the UI won’t update, it’s usually because you’re seeing a saved copy from React Query, Next.js, the browser, a CDN, or a service worker. And sometimes it’s not a cache at all, it’s local React state

In this tutorial, you’ll learn how to build an AI-powered social media post scheduler using Gemini, Late API, and Next.js.

We’ll use the Gemini API to generate engaging social media content from user prompts, Next.js to handle both the frontend and backend of the application, and Late API to publish and schedule posts across multiple social media platforms from a single platform.

Table of Contents

• Prerequisites

• Setup and Installation

• How to Schedule Social Media Posts with Late

• How to Build the Next.js App Interface

• How to integrate Gemini API for Post Generation

• How to Use Late API in Next.js

• Conclusion

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of React or Next.js.

We will use the following tools:

• Late API: A social media API that lets you create and schedule posts across 13 social media platforms from a single dashboard.

• Next.js: A React framework for building fast, scalable web applications, handling both the frontend and backend.

• Google Gemini API: Provides access to Google’s AI models for generating text and other content based on user prompts.

Setup and Installation

Create a new Next.js project using the following code snippet:

npx create-next-app post-scheduler

Install the project dependencies. We’ll use Day.js to work with JavaScript dates, making it easier to schedule and publish social media posts at the correct time.

npm install @google/genai dayjs utc

Next, add a .env.local file containing your Gemini API key at the root of your Next.js project:

GEMINI_API_KEY=<paste_your API key>

Once everything is set up, your Next.js project is ready. Now, let's start building! 🚀

How to Schedule Social Media Posts with Late

Late is an all-in-one social media scheduling platform that allows you to connect your social media accounts and publish posts across multiple platforms. In this section, you’ll learn how to create and schedule social media posts using the Late dashboard.

To get started, create a Late account and sign in.

Create an API key and add it to the .env.local file within your Next.js project.

LATE_API_KEY=<your_API_key>

Connect your social media accounts to Late so you can manage and publish posts across all platforms.

After connecting your social media accounts via OAuth, you can start writing, posting, and scheduling content directly to your social media platforms.

Late lets you write your post content and attach media files directly from the dashboard.

You can choose when your content should be published: post immediately, schedule for later, add it to a job queue, or save it as a draft.

Once a post is published, you can view its status and preview it directly in the dashboard using the post link.

🎉 Congratulations! You’ve successfully created your first post using the Late dashboard. In the next sections, you’ll learn how to use the Late API to create and schedule posts directly from your applications.

How to Build the Next.js App Interface

In this section, you’ll build the user interface for the application. The app uses a single-page route with conditional rendering to display recent posts, an AI prompt input field, and a form that allows users to create or schedule posts.

Before we proceed, create a types.d.ts file within your Next.js project and copy the following code snippet into the file:

interface Post {
    _id: string;
    content: string;
    scheduledFor: string;
    status: string;
}

interface AIFormProps {
    handleGeneratePost: (e: React.FormEvent<HTMLFormElement>) => void;
    useAI: boolean;
    setUseAI: React.Dispatch<React.SetStateAction<boolean>>;
    prompt: string;
    setPrompt: React.Dispatch<React.SetStateAction<string>>;
    disableBtn: boolean;
}

interface FormProps {
    handlePostSubmit: (e: React.FormEvent<HTMLFormElement>) => void;
    content: string;
    setContent: React.Dispatch<React.SetStateAction<string>>;
    date: string;
    setDate: React.Dispatch<React.SetStateAction<string>>;
    disableBtn: boolean;
    setUseAI: React.Dispatch<React.SetStateAction<boolean>>;
    useAI: boolean;
}

The types.d.ts file defines all the data structures and type declarations used throughout the application.

Copy the following code snippet into the app/page.tsx file:

"use client";
import Nav from "./components/Nav";
import { useState } from "react";
import NewPost from "./components/NewPost";
import PostsQueue from "./components/PostsQueue";

export default function Page() {
    const [showPostQueue, setShowPostQueue] = useState<boolean>(false);
    return (
        <div className='w-full h-screen'>
            <Nav showPostQueue={showPostQueue} setShowPostQueue={setShowPostQueue} />
            {showPostQueue ? <PostsQueue /> : <NewPost />}
        </div>
    );
}

The Page component renders the Nav component and uses conditional rendering to display either the PostsQueue or NewPost component based on the value of the showPostQueue state.

Create a components folder to store the page components used in the application.

cd app
mkdir components && cd components
touch Nav.tsx NewPost.tsx PostElement.tsx PostsQueue.tsx

Add the code snippet below to the Nav.tsx file:

export default function Nav({
    showPostQueue,
    setShowPostQueue,
}: {
    showPostQueue: boolean;
    setShowPostQueue: React.Dispatch<React.SetStateAction<boolean>>;
}) {
    return (
        <nav>
            <h2>Post Scheduler</h2>

            <button onClick={() => setShowPostQueue(!showPostQueue)}>
                {showPostQueue ? "New Post" : "Schedule Queue"}
            </button>
        </nav>
    );
}

Copy the following code snippet into the PostsQueue.tsx file:

"use client";
import { useEffect, useState, useCallback } from "react";
import PostElement from "./PostElement";

export default function PostsQueue() {
    const [posts, setPosts] = useState<Post[]>([]);
    const [loading, setLoading] = useState<boolean>(true);

    return (
        <div className='p-4'>
            <h2 className='text-xl font-bold'>Scheduled Posts</h2>

            {loading ? (
                <p className='text-sm'>Loading scheduled posts...</p>
            ) : (
                <div className='mt-4'>
                    {posts.length > 0 ? (
                        posts.map((post) => <PostElement key={post._id} post={post} />)
                    ) : (
                        <p>No scheduled posts available.</p>
                    )}
                </div>
            )}
        </div>
    );
}

The PostsQueue.tsx component displays a list of previously created posts along with their current status, showing whether each post has been published or scheduled for a later time. While the data is being loaded, it shows a loading message, and once loaded, it renders each post using the PostElement component.

Add the following to the PostElement.tsx component:

export default function PostElement({ post }: { post: Post }) {
    export const formatReadableTime = (isoString: string) => {
        const date = new Date(isoString); // parses UTC automatically
        return date.toLocaleString(undefined, {
            year: "numeric",
            month: "short",
            day: "numeric",
            hour: "2-digit",
            minute: "2-digit",
            second: "2-digit",
            hour12: true, // set to false for 24h format
        });
    };

    return (
        <div className='p-4 border flex items-center justify-between  space-x-4 rounded mb-2 hover:bg-gray-100 cursor-pointer'>
            <div>
                <p className='font-semibold text-sm'>{post.content.slice(0, 100)}</p>
                <p className='text-blue-400 text-xs'>
                    Scheduled for: {formatReadableTime(post.scheduledFor)}
                </p>
            </div>

            <p className='text-sm text-red-500'>{post.status}</p>
        </div>
    );
}

Finally, copy the following code snippet into the NewPost.tsx file:

"use client";
import { useState } from "react";

export default function NewPost() {
 const [disableBtn, setDisableBtn] = useState<boolean>(false);
 const [useAI, setUseAI] = useState<boolean>(false);
 const [content, setContent] = useState<string>("");
 const [prompt, setPrompt] = useState<string>("");
 const [date, setDate] = useState<string>("");

 //👇🏻 generates post content
 const handleGeneratePost = async (e: React.FormEvent<HTMLFormElement>) => {
  e.preventDefault();
  setDisableBtn(true);
 };

 //👇🏻 create/schedule post
 const handlePostSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
  e.preventDefault();
 };

 return (
  <div className='w-full p-4  h-[90vh] flex flex-col items-center justify-center border-t'>
   <h3 className='text-xl font-bold'>New Post</h3>

   {useAI ? (
    <AIPromptForm
     handleGeneratePost={handleGeneratePost}
     useAI={useAI}
     setUseAI={setUseAI}
     prompt={prompt}
     setPrompt={setPrompt}
     disableBtn={disableBtn}
    />
   ) : (
    <PostForm
     handlePostSubmit={handlePostSubmit}
     content={content}
     setContent={setContent}
     date={date}
     setDate={setDate}
     disableBtn={disableBtn}
     setUseAI={setUseAI}
     useAI={useAI}
    />
   )}
  </div>
 );
}

The NewPost component conditionally renders the AIPromptForm and the PostForm. When a user chooses to generate content using AI, the AIPromptForm component is displayed to collect the prompt. Once the content is generated, the PostForm component is shown, allowing the user to edit, create, or schedule the post.

Add the components below inside the NewPost.tsx file:

export const AIPromptForm = ({
    handleGeneratePost,
    useAI,
    setUseAI,
    prompt,
    setPrompt,
    disableBtn,
}: AIFormProps) => {
    return (
        <form onSubmit={handleGeneratePost}>
            <p onClick={() => setUseAI(!useAI)}>Exit AI </p>
            <textarea
                rows={3}
                required
                value={prompt}
                onChange={(e) => setPrompt(e.target.value)}
                placeholder='Enter prompt...'
            />
            <button type='submit' disabled={disableBtn}>
                {disableBtn ? "Generating..." : "Generate Post with AI"}
            </button>
        </form>
    );
};

// 👇🏻 Post Form component
export const PostForm = ({
    handlePostSubmit,
    content,
    setContent,
    date,
    setDate,
    disableBtn,
    setUseAI,
    useAI,
}: FormProps) => {
    const getNowForDatetimeLocal = () => {
        const now = new Date();
        return new Date(now.getTime() - now.getTimezoneOffset() * 60000)
            .toISOString()
            .slice(0, 16);
    };

    return (
        <form onSubmit={handlePostSubmit}>
            <p onClick={() => setUseAI(!useAI)}>Generate posts with AI </p>
            <textarea
                value={content}
                onChange={(e) => setContent(e.target.value)}
                rows={4}
                placeholder="What's happening?"
                required
                maxLength={280}
            />
            <input
                type='datetime-local'
                min={getNowForDatetimeLocal()}
                value={date}
                onChange={(e) => setDate(e.target.value)}
            />
            <button disabled={disableBtn} type='submit'>
                {disableBtn ? "Posting..." : "Create post"}
            </button>
        </form>
    );
};

Congratulations! You've completed the application interface.

How to integrate Gemini API for Post Generation

Here, you will learn how to generate post content from the user's prompt using the Gemini API.

Before we proceed, make sure you have copied your API key from the Google AI Studio.

Create an api folder inside the Next.js app directory. This folder will contain the API routes used to generate AI content and create or schedule posts using the Late API.

cd app && mkdir api

Next, create a generate folder inside the api directory and add a route.ts file. Copy the following code into the file:

// 👇🏻 In api/generate/route.ts file
import { NextRequest, NextResponse } from "next/server";
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });

export async function POST(req: NextRequest) {
    const { prompt } = await req.json();

    try {
        const response = await ai.models.generateContent({
            model: "gemini-3-flash-preview",
            contents: `
    You are a social media post generator, very efficient in generating engaging posts for Twitter (X). Given a topic, generate a creative and engaging post that captures attention and encourages interaction. This posts will always be within the character limit of X (Twitter) which is 280 characters, which includes any hashtags or mentions, spaces, punctuation, and emojis.

    The user will provide a topic or theme, and you will generate a post based on that input.
    Here is the instruction from the user:
    "${prompt}"`,
        });
        if (!response.text) {
            return NextResponse.json(
                {
                    message: "Encountered an error generating the post.",
                    success: false,
                },
                { status: 400 },
            );
        }

        return NextResponse.json(
            { message: response.text, success: true },
            { status: 200 },
        );
    } catch (error) {
        return NextResponse.json(
            { message: "Error generating post.", success: false },
            { status: 500 },
        );
    }
}

The api/generate endpoint accepts the user's prompt and generates post content using the Gemini API.

Now you can send a request to the newly created /api/generate endpoint from the NewPost component. Update the handleGeneratePost function as shown below:

const handleGeneratePost = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    setDisableBtn(true);
    const result = await fetch("/api/generate", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
        },
        body: JSON.stringify({ prompt }),
    });

    const data = await result.json();
    if (data.success) {
        setUseAI(false);
        setContent(data.message);
        setPrompt("");
    }
    setDisableBtn(false);
};

The handleGeneratePost function accepts the user's prompt and returns the AI-generated content.

How to Use Late API in Next.js

Late provides API endpoints that let you create, schedule, and manage posts programmatically. This allows you to integrate social media posting directly into your applications or automation workflows.

To get started, copy your Late API key and the account ID of your social media platforms into the .env.local file:

LATE_API_KEY=<Late_API_key>
ACCOUNT_ID=<social_media_acct_id>

# Gemini API key
GEMINI_API_KEY=<gemini_API_key>

Note: In this tutorial, we will be using Twitter (X) as the social media platform for scheduling posts. You can adapt the same workflow to other platforms supported by Late API by updating the platform and accountId values in your API requests.

Create an api/post endpoint to accept post content and schedule or publish posts using the Late API.

cd api
mkdir post && cd post
touch route.ts

Then, add the following POST method to post/route.ts:

import { NextRequest, NextResponse } from "next/server";
import utc from "dayjs/plugin/utc";
import dayjs from "dayjs";

dayjs.extend(utc);

export async function POST(req: NextRequest) {
    const { content, publishAt } = await req.json();

    // Determine if the post should be scheduled or published immediately
    const nowUTC = publishAt ? dayjs(publishAt).utc() : null;
    const publishAtUTC = nowUTC ? nowUTC.format("YYYY-MM-DDTHH:mm") : null;

    try {
        const response = await fetch("https://getlate.dev/api/v1/posts", {
            method: "POST",
            headers: {
                Authorization: `Bearer ${process.env.LATE_API_KEY}`,
                "Content-Type": "application/json",
            },
            body: JSON.stringify({
                content,
                platforms: [
                    {
                        platform: "twitter",
                        accountId: process.env.ACCOUNT_ID!,
                    },
                ],
                publishNow: !publishAt,
                scheduledFor: publishAtUTC,
            }),
        });

        const { post, message } = await response.json();

        if (post?._id) {
            return NextResponse.json({ message, success: true }, { status: 201 });
        }

        return NextResponse.json({ message: "Error occurred", success: false }, { status: 500 });
    } catch (error) {
        return NextResponse.json({ message: "Error scheduling post.", success: false }, { status: 500 });
    }
}

From the code snippet above:

• The api/post endpoint accepts the post’s content and an optional publishAt time.

• If publishAt is null, the post is published immediately. Otherwise, the time is converted to UTC for scheduling.

• It then sends a request to the Late API using your API key and the account ID to create or schedule the post on the selected social media platform.

You can also add a GET method to the /api/post endpoint to retrieve posts that have already been created or scheduled:

export async function GET() {
    try {
        const response = await fetch(
            "https://getlate.dev/api/v1/posts?platform=twitter",
            {
                method: "GET",
                headers: {
                    Authorization: `Bearer ${process.env.LATE_API_KEY}`,
                    "Content-Type": "application/json",
                },
            },
        );

        const { posts } = await response.json();

        return NextResponse.json({ posts }, { status: 200 });
    } catch (error) {
        return NextResponse.json(
            { message: "Error fetching posts.", success: false },
            { status: 500 },
        );
    }
}

Next, update the handlePostSubmit function in NewPost.tsx to send a POST request to /api/post. This will create or schedule the post and notify the user of the result:

const handlePostSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    setDisableBtn(true);

    const now = new Date();
    const selected = date ? new Date(date) : null;
    const publishAt = !selected || selected <= now ? null : date;

    const result = await fetch("/api/post", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ content, publishAt }),
    });

    const { message, success } = await result.json();

    if (success) {
        setContent("");
        setDate("");
        alert("Success: " + message);
    } else {
        alert("Error: " + message);
    }

    setDisableBtn(false);
};

Finally, fetch all scheduled or published posts and render them in the PostsQueue component:

const fetchScheduledPosts = useCallback(async () => {
    try {
        const response = await fetch("/api/post", {
            method: "GET",
            headers: { "Content-Type": "application/json" },
        });
        const data = await response.json();
        setPosts(data.posts);
        setLoading(false);
    } catch (error) {
        console.error("Error fetching scheduled posts:", error);
        setLoading(false);
    }
}, []);

useEffect(() => {
    fetchScheduledPosts();
}, [fetchScheduledPosts]);

🎉 Congratulations! You’ve successfully built an AI-powered social media post scheduler using Next.js, Gemini API, and Late API.

The source code for this tutorial is available on GitHub.

Conclusion

In this tutorial, you’ve learnt how to create and schedule social media posts across multiple platforms using a single scheduling platform, Late, and how to generate AI content using the Gemini API.

The Late API is a powerful tool for automating social media tasks, posting at specific intervals, managing multiple accounts, and tracking analytics – all from one platform. By combining it with generative AI models like Gemini and automation tools like n8n or Zapier, you can build automated workflows that keep your audience engaged with minimal effort.

The Gemini API also makes it easy to integrate AI-powered text, images, or code generation directly into your applications, opening up a wide range of creative possibilities.

Thank you for reading! 🎉

By the end of this guide, you'll have a fully functional application that can:

• Upload and process PDF, DOCX, and TXT files

• Store documents in Supabase Storage

• Generate embeddings using OpenAI

• Perform semantic search across document chunks

• Provide AI-generated answers based on document content

• View and manage uploaded documents

This is a production-ready solution that you can deploy and use immediately.

Table of Contents

• What You'll Learn

• Prerequisites

• Understanding the Technologies

• Project Overview

• Step 1: Create Your Next.js Project

• Step 2: Install Required Dependencies

• Step 3: Set Up Your Supabase Project

• Step 4: Configure Environment Variables

• Step 5: Create the Upload API Route

• Step 6: Create the RAG Search API Route

• Step 7: Create the Documents API Route

• Step 8: Create the Upload Modal Component

• Step 9: Create the PDF Viewer Modal Component

• Step 10: Create the Navigation Component

• Step 11: Create the Home Page (Search Interface)

• Step 12: Create the Documents Page

• Step 13: Test Your Application

• Step 14: Deploy Your Application

• How RAG Search Works

• Troubleshooting Common Issues

• Next Steps

• Conclusion

What You'll Learn

In this handbook, you'll learn how to:

• Set up a Next.js application with TypeScript

• Configure Supabase for database and file storage

• Integrate OpenAI embeddings and chat completions

• Implement document text extraction and chunking

• Build a vector search system using PostgreSQL

• Create a modern UI with React components

• Handle file uploads and storage

• Implement RAG (Retrieval-Augmented Generation) search

Prerequisites

Before you begin, make sure you have:

• Node.js 18 or higher installed on your computer

• A Supabase account (free tier works fine)

• An OpenAI API key

• Basic knowledge of React and TypeScript

• Familiarity with Next.js (helpful but not required)

Understanding the Technologies

Before we dive into building the application, you should understand the key technologies and concepts you'll be working with:

What is RAG (Retrieval-Augmented Generation)?

RAG is an AI pattern that combines information retrieval with text generation. Instead of relying solely on an AI model's training data, RAG retrieves relevant information from your own documents. It then uses that information as context to generate accurate, up-to-date answers. This approach gives you:

• Accuracy: Answers are based on your actual documents, not just the AI's training data

• Transparency: You can see which document sections were used to generate the answer

• Efficiency: Only relevant document chunks are used, reducing token costs

What are Embeddings and Vector Database?

Embeddings are numerical representations of text that capture semantic meaning. When you convert text to an embedding, similar meanings are represented by similar numbers. For example, "dog" and "puppy" would have similar embeddings. Meanwhile, "dog" and "airplane" would have very different ones.

OpenAI's embedding models convert text into vectors. These are arrays of numbers that can be compared mathematically. This allows you to find documents that are semantically similar to a search query. You can find matches even if they don't contain the exact same words.

A vector database is a specialized database designed to store and search through embeddings efficiently. Instead of searching for exact text matches, vector databases use mathematical operations. They use operations like cosine similarity to find the most semantically similar content.

In this tutorial, you'll use Supabase's PostgreSQL database with the pgvector extension. This extension adds vector storage and similarity search capabilities to PostgreSQL. This lets you store embeddings alongside your regular database data. You can also perform fast similarity searches.

What is Text Chunking?

Text chunking is the process of breaking large documents into smaller, manageable pieces. This is necessary for several reasons.

First, AI models have token limits. These are maximum input sizes. Second, smaller chunks allow for more precise retrieval. Third, overlapping chunks ensure context isn't lost at boundaries.

You'll use LangChain's RecursiveCharacterTextSplitter. This tool intelligently splits text while trying to preserve sentence and paragraph boundaries.

What is Supabase?

Supabase is an open-source Firebase alternative. It provides several key features.

You get a PostgreSQL database, which is a powerful, open-source relational database. You also get storage, which is file storage similar to AWS S3. There are real-time features that provide real-time subscriptions to database changes. Finally, there's built-in user authentication.

For this project, you'll use Supabase's database to store document chunks and embeddings. You'll also use Supabase Storage to store the original uploaded files.

What is Tailwind CSS?

Tailwind CSS is a utility-first CSS framework that lets you style your application by applying pre-built utility classes directly in your HTML/JSX. Instead of writing custom CSS, you use classes like bg-blue-600, text-white, and rounded-lg to style elements.

You'll use Tailwind CSS in this project because it speeds up development by providing ready-made styling utilities. It also ensures consistent design across the application. Plus, it makes it easy to create responsive, modern UIs. Finally, it works seamlessly with Next.js.

Now that you understand the core concepts and tools we’ll be using, let's start building the application.

Project Overview

Your RAG search application will consist of:

1. Frontend: Next.js application with React components for uploading documents and searching

2. Backend API Routes: Next.js API routes for handling uploads, searches, and document management

3. Database: Supabase PostgreSQL with vector extension for storing embeddings

4. Storage: Supabase Storage for storing original files

5. AI Integration: OpenAI for generating embeddings and chat completions

The application will have two main pages:

• Search Page: Where users can ask questions about their uploaded documents and get AI-generated answers

• Documents Page: Where users can view all uploaded documents, upload new ones, preview files, and manage their document library

Let's start building!

If you ever get stuck on the source code, you can view it on GitHub here:

https://github.com/mayur9210/rag-search-app

Step 1: Create Your Next.js Project

Start by creating a new Next.js project with TypeScript. Open your terminal and run:

npx create-next-app@latest rag-search-app --typescript --tailwind --app

When prompted, choose the following options:

• TypeScript: Yes

• ESLint: Yes

• Tailwind CSS: Yes

• App Router: Yes (default)

• Customize import alias: No

Navigate into your project directory:

cd rag-search-app

Now that your project is set up, you'll need to install the additional packages required for document processing, AI integration, and database operations.

Step 2: Install Required Dependencies

You'll need several packages for this project. You can install them using npm:

npm install @supabase/supabase-js @langchain/openai @langchain/textsplitters langchain openai mammoth pdf2json

Here's what each package does:

• @supabase/supabase-js: Client library for interacting with Supabase (database and storage)

• @langchain/openai: LangChain integration for OpenAI (helps with text processing)

• @langchain/textsplitters: Text splitting utilities for chunking documents into smaller pieces

• langchain: Core LangChain library (provides AI workflow tools)

• openai: Official OpenAI SDK (for generating embeddings and chat completions)

• mammoth: Converts DOCX files to plain text

• pdf2json: Extracts text from PDF files

Install the TypeScript types for pdf2json:

npm install --save-dev @types/pdf-parse

With all dependencies installed, you're ready to set up your Supabase project, which will handle your database and file storage needs.

Step 3: Set Up Your Supabase Project

Create a Supabase Project

First, you’ll need to create a new Supabase project, which you can do by following these steps:

1. Go to supabase.com and sign in or create an account

2. Click "New Project"

3. Fill in your project details:

   • Name: rag-search-app (or any name you prefer)

   • Database Password: Choose a strong password (save this – you'll need it)

   • Region: Select the region closest to you

4. Click "Create new project" and wait for it to be ready (this takes a few minutes)

Get Your Supabase Credentials

Once your project is ready, go to Settings and then API.

Copy the following values:

• Project URL (this is your NEXT_PUBLIC_SUPABASE_URL)

• anon public key (this is your NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY)

• service_role key (this is your SUPABASE_SERVICE_ROLE_KEY)

Important: Keep your service role key secret. Never expose it in client-side code. It bypasses Row-Level Security (RLS) policies, which is necessary for server-side file uploads but should never be used in browser code.

Set Up the Database Schema

Now you'll set up the database structure to store your documents and embeddings. Go to SQL Editor in your Supabase dashboard and run the following SQL:

-- Enable the vector extension for embeddings
-- This extension allows PostgreSQL to store and search vector data efficiently
CREATE EXTENSION IF NOT EXISTS vector;

-- Create the documents table
-- This table stores document chunks, their metadata, and embeddings
CREATE TABLE documents (
  id BIGSERIAL PRIMARY KEY,
  content TEXT NOT NULL,
  metadata JSONB,
  embedding vector(1536)  -- OpenAI's text-embedding-3-small produces 1536-dimensional vectors
  file_path text null,
  file_url text null,
);

-- Create an index on the embedding column for faster similarity search
-- The ivfflat index speeds up vector similarity queries
CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops);

-- Create a function for matching documents based on similarity
-- This function finds the most similar document chunks to a query embedding
CREATE OR REPLACE FUNCTION match_documents(
  query_embedding vector(1536),
  match_threshold float,
  match_count int
)
RETURNS TABLE (
  id bigint,
  content text,
  metadata jsonb,
  similarity float
)
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN QUERY
  SELECT
    documents.id,
    documents.content,
    documents.metadata,
    1 - (documents.embedding <=> query_embedding) AS similarity
  FROM documents
  WHERE 1 - (documents.embedding <=> query_embedding) > match_threshold
  ORDER BY documents.embedding <=> query_embedding
  LIMIT match_count;
END;
$$;

This SQL does the following:

• Enables the vector extension: This adds vector storage and similarity search capabilities to PostgreSQL

• Creates the documents table: Stores document chunks, metadata (file name, type, and so on), and their embeddings

• Creates an index: Speeds up similarity searches on the embedding column

• Creates a match function: Finds the most similar document chunks to a query embedding using cosine similarity

The <=> operator calculates cosine distance between vectors. A smaller distance means more similar content.

Set Up Supabase Storage

You’ll need a storage bucket to store uploaded files. This is separate from the database and holds the original PDF, DOCX, and TXT files.

To set up your storage bucket:

1. Go to Storage in your Supabase dashboard

2. Click New bucket

3. Name it documents

4. Set it to Public (this allows file downloads)

5. Click Create bucket

If you prefer a private bucket, you can use the service role key for server-side operations, which bypasses Row-Level Security policies. For this tutorial, a public bucket is simpler and works well.

Now that your Supabase project is configured, you'll set up your environment variables to connect your Next.js application to Supabase and OpenAI.

Step 4: Configure Environment Variables

Create a .env.local file in your project root:

NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
OPENAI_API_KEY=your_openai_api_key

Replace the placeholder values with your actual credentials:

• Get Supabase values from Settings → API in your Supabase dashboard

• Get your OpenAI API key from platform.openai.com/api-keys

Security Note: Never commit .env.local to version control. It's already in .gitignore by default, but double-check to ensure your secrets stay secure.

With your environment configured, you're ready to start building the API routes that will handle file uploads, searches, and document management.

Step 5: Create the Upload API Route

Now you'll create the API route that handles file uploads. This route will process uploaded files, extract their text, split them into chunks, generate embeddings, and store everything in your database and storage.

Create src/app/api/upload/route.ts:

import { createClient } from '@supabase/supabase-js';
import OpenAI from 'openai';
import { NextResponse } from 'next/server';
import { RecursiveCharacterTextSplitter } from '@langchain/textsplitters';
import mammoth from 'mammoth';

const url = process.env.NEXT_PUBLIC_SUPABASE_URL!;
const anonKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY!;
const serviceKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
const supabaseStorage = createClient(url, serviceKey || anonKey);
const supabase = createClient(url, anonKey);
const openai = new OpenAI();

function safeDecodeURIComponent(str: string): string {
  try { 
    return decodeURIComponent(str); 
  } catch { 
    try { 
      return decodeURIComponent(str.replace(/%/g, '%25')); 
    } catch { 
      return str; 
    } 
  }
}

async function extractTextFromFile(file: File): Promise<string> {
  const buffer = Buffer.from(await file.arrayBuffer());
  const fileName = file.name.toLowerCase();

  if (fileName.endsWith('.pdf')) {
    const PDFParser = (await import('pdf2json')).default;
    return new Promise((resolve, reject) => {
      const pdfParser = new (PDFParser as any)(null, true);
      pdfParser.on('pdfParser_dataError', (err: any) => 
        reject(new Error(`PDF parsing error: ${err.parserError}`))
      );
      pdfParser.on('pdfParser_dataReady', (pdfData: any) => {
        try {
          let fullText = '';
          pdfData.Pages?.forEach((page: any) => 
            page.Texts?.forEach((text: any) => 
              text.R?.forEach((r: any) => 
                r.T && (fullText += safeDecodeURIComponent(r.T) + ' ')
              )
            )
          );
          resolve(fullText.trim());
        } catch (error: any) {
          reject(new Error(`Error extracting text: ${error.message}`));
        }
      });
      pdfParser.parseBuffer(buffer);
    });
  } else if (fileName.endsWith('.docx')) {
    const result = await mammoth.extractRawText({ buffer });
    return result.value;
  } else if (fileName.endsWith('.txt')) {
    return buffer.toString('utf-8');
  } else {
    throw new Error('Unsupported file type. Please upload PDF, DOCX, or TXT files.');
  }
}

export async function POST(req: Request) {
  try {
    const file = (await req.formData()).get('file') as File;
    if (!file) {
      return NextResponse.json({ error: 'No file provided' }, { status: 400 });
    }

    const documentId = crypto.randomUUID();
    const uploadDate = new Date().toISOString();
    const filePath = `${documentId}.${file.name.split('.').pop() || 'bin'}`;

    // Upload file to Supabase Storage
    const fileBuffer = Buffer.from(await file.arrayBuffer());
    const { error: storageError } = await supabaseStorage.storage
      .from('documents')
      .upload(filePath, fileBuffer, {
        contentType: file.type || 'application/octet-stream',
        upsert: false,
      });

    if (storageError) {
      const msg = storageError.message || 'Unknown storage error';
      if (msg.includes('row-level security') || msg.includes('RLS')) {
        return NextResponse.json({ 
          success: false, 
          error: `Storage RLS error: ${msg}. Ensure SUPABASE_SERVICE_ROLE_KEY is set.` 
        }, { status: 500 });
      }
      return NextResponse.json({ 
        success: false, 
        error: `Failed to store file: ${msg}` 
      }, { status: 500 });
    }

    // Get public URL for the file
    const { data: urlData } = supabaseStorage.storage
      .from('documents')
      .getPublicUrl(filePath);

    // Extract text from file
    const text = await extractTextFromFile(file);
    if (!text || text.trim().length === 0) {
      return NextResponse.json({ 
        error: 'Could not extract text from file' 
      }, { status: 400 });
    }

    // Split text into chunks
    // Chunk size of 800 characters with 100-character overlap ensures
    // we don't lose context at chunk boundaries
    const textSplitter = new RecursiveCharacterTextSplitter({
      chunkSize: 800,
      chunkOverlap: 100,
    });
    const chunks = await textSplitter.splitText(text);

    // Process each chunk: generate embedding and store in database
    for (let i = 0; i < chunks.length; i++) {
      const chunk = chunks[i];

      // Generate embedding using OpenAI
      // This converts the text chunk into a 1536-dimensional vector
      const emb = await openai.embeddings.create({
        model: 'text-embedding-3-small',
        input: chunk,
      });

      // Store chunk with embedding in database
      const { error } = await supabase.from('documents').insert({
        content: chunk,
        metadata: { 
          source: file.name,
          document_id: documentId,
          file_name: file.name,
          file_type: file.type || file.name.split('.').pop(),
          file_size: file.size,
          upload_date: uploadDate,
          chunk_index: i,
          total_chunks: chunks.length,
          file_path: filePath,
          file_url: urlData.publicUrl,
        },
        embedding: JSON.stringify(emb.data[0].embedding),
      });

      if (error) {
        return NextResponse.json({ 
          success: false, 
          error: error.message 
        }, { status: 500 });
      }
    }

    return NextResponse.json({ 
      success: true, 
      documentId, 
      fileName: file.name, 
      chunks: chunks.length, 
      textLength: text.length, 
      fileUrl: urlData.publicUrl 
    });
  } catch (error: any) {
    return NextResponse.json({ 
      success: false, 
      error: error.message || 'Failed to process file' 
    }, { status: 500 });
  }
}

This route handles the complete upload workflow:

1. Receives the file from the client via FormData

2. Generates a unique document ID using crypto.randomUUID()

3. Uploads the file to Supabase Storage for safekeeping

4. Extracts text based on file type (PDF, DOCX, or TXT)

5. Splits the text into chunks of 800 characters with 100-character overlap

6. Generates embeddings for each chunk using OpenAI's embedding model

7. Stores each chunk with its embedding and metadata in the database

The overlap between chunks ensures that if a sentence or concept spans a chunk boundary, it won't be lost. Now that you can upload and process documents, let's create the search functionality.

Step 6: Create the RAG Search API Route

This route implements the core RAG functionality: it takes a user's query, finds the most relevant document chunks, and uses them to generate an accurate answer.

Create src/app/api/search/route.ts:

import { createClient } from '@supabase/supabase-js';
import OpenAI from 'openai';
import { NextResponse } from 'next/server';

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY!
);
const openai = new OpenAI();

export async function POST(req: Request) {
  try {
    const { query } = await req.json();

    // Generate embedding for the user's query
    // This converts the search query into the same vector space as document chunks
    const emb = await openai.embeddings.create({ 
      model: 'text-embedding-3-small', 
      input: query 
    });

    // Find similar documents using vector similarity search
    // The match_documents function finds the 5 most similar chunks
    const { data: results, error } = await supabase.rpc('match_documents', {
      query_embedding: JSON.stringify(emb.data[0].embedding),
      match_threshold: 0.0,  // Accept any similarity (you can increase this for stricter matching)
      match_count: 5,        // Return top 5 most similar chunks
    });

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    // Combine retrieved chunks into context
    // These chunks will be used as context for the AI to generate an answer
    const context = results?.map((r: any) => r.content).join('\n---\n') || '';

    // Generate answer using OpenAI with retrieved context
    // This is the "Generation" part of RAG
    const completion = await openai.chat.completions.create({
      model: 'gpt-4o-mini',
      messages: [
        { 
          role: 'system', 
          content: 'You are a helpful assistant. Use the provided context to answer questions. If the answer is not in the context, say you do not know.' 
        },
        { 
          role: 'user', 
          content: `Context: ${context}\n\nQuestion: ${query}` 
        }
      ],
    });

    return NextResponse.json({ 
      answer: completion.choices[0].message.content, 
      sources: results 
    });
  } catch (error: any) {
    return NextResponse.json({ error: error.message }, { status: 500 });
  }
}

This route implements the RAG pattern. Here's how the complete RAG workflow works:

1. Converts the query to an embedding: The user's question is transformed into the same vector space as your document chunks. This uses the same embedding model (text-embedding-3-small) that processed the documents, ensuring they're in the same "vector space."

2. Searches for similar chunks: Uses the match_documents function to find the 5 most semantically similar document chunks. This uses cosine similarity on the embeddings. Cosine similarity measures the angle between vectors - smaller angles mean more similar content, even if the exact words differ.

3. Uses chunks as context: The retrieved chunks are passed to GPT-4o-mini as context. These chunks contain the most relevant information from your documents.

4. Generates an answer: The AI model generates an answer based on the provided context. The system prompt instructs the AI to only answer based on the provided context, ensuring accuracy and preventing hallucinations.

5. Returns results: Both the answer and source chunks are returned so users can verify the information.

This RAG approach gives you several benefits. First, you get accuracy because answers are based on your actual documents, not just the AI's training data. Second, you get transparency because you can see which document chunks were used to generate each answer. Third, you get efficiency because only relevant chunks are used, which reduces token usage and costs. Finally, you get up-to-date information because you can update your knowledge base by uploading new documents without retraining the AI.

Now let's create the API route for managing documents.

Step 7: Create the Documents API Route

This route handles listing, viewing, downloading, and deleting documents. It serves multiple purposes depending on the query parameters.

Create src/app/api/documents/route.ts:

import { createClient } from '@supabase/supabase-js';
import { NextResponse } from 'next/server';

const url = process.env.NEXT_PUBLIC_SUPABASE_URL!;
const anonKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY!;
const serviceKey = process.env.SUPABASE_SERVICE_ROLE_KEY || anonKey;
const supabase = createClient(url, anonKey);
const supabaseStorage = createClient(url, serviceKey);

export async function GET(req: Request) {
  try {
    const reqUrl = new URL(req.url);
    const id = reqUrl.searchParams.get('id');
    const file = reqUrl.searchParams.get('file') === 'true';
    const view = reqUrl.searchParams.get('view') === 'true';

    // Handle file download/view
    if (id && file) {
      const { data: documents } = await supabase
        .from('documents')
        .select('metadata')
        .eq('metadata->>document_id', id)
        .limit(1);

      if (!documents || documents.length === 0) {
        return NextResponse.json({ error: 'Document not found' }, { status: 404 });
      }

      const meta = documents[0].metadata;
      const fileName = meta?.file_name || 'document';
      const fileType = meta?.file_type || 'application/octet-stream';
      const filePath = meta?.file_path || `${id}.${fileName.split('.').pop() || 'pdf'}`;

      const { data: fileData, error: downloadError } = await supabaseStorage.storage
        .from('documents')
        .download(filePath);

      if (downloadError || !fileData) {
        return NextResponse.json({ 
          error: downloadError?.message || 'File not stored' 
        }, { status: 404 });
      }

      const buffer = Buffer.from(await fileData.arrayBuffer());
      if (buffer.length === 0) {
        return NextResponse.json({ error: 'File is empty' }, { status: 500 });
      }

      const isPDF = fileType === 'application/pdf' || fileName.toLowerCase().endsWith('.pdf');
      return new NextResponse(new Uint8Array(buffer), {
        headers: {
          'Content-Type': fileType,
          'Content-Disposition': (view && isPDF) 
            ? `inline; filename="${fileName}"` 
            : `attachment; filename="${fileName}"`,
          'Content-Length': buffer.length.toString(),
          ...(view && isPDF ? { 'X-Content-Type-Options': 'nosniff' } : {}),
        },
      });
    }

    // Get single document with text content
    if (id) {
      const { data: chunks, error } = await supabase
        .from('documents')
        .select('content, metadata')
        .eq('metadata->>document_id', id)
        .order('metadata->>chunk_index', { ascending: true });

      if (error || !chunks || chunks.length === 0) {
        return NextResponse.json({ error: 'Document not found' }, { status: 404 });
      }

      const m = chunks[0].metadata || {};
      return NextResponse.json({
        id,
        file_name: m.file_name || 'Unknown',
        file_type: m.file_type || 'unknown',
        file_size: m.file_size || 0,
        upload_date: m.upload_date || new Date().toISOString(),
        total_chunks: chunks.length,
        fullText: chunks.map((c: any) => c.content).join('\n\n'),
        file_url: m.file_url,
        file_path: m.file_path
      });
    }

    // List all documents
    const { data: documents, error } = await supabase
      .from('documents')
      .select('metadata');

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    // Deduplicate documents by document_id
    // Since each document is split into multiple chunks, we need to group them
    const map = new Map();
    documents?.forEach((doc: any) => {
      const m = doc.metadata;
      if (m?.document_id && !map.has(m.document_id)) {
        map.set(m.document_id, {
          id: m.document_id,
          file_name: m.file_name || 'Unknown',
          file_type: m.file_type || 'unknown',
          file_size: m.file_size || 0,
          upload_date: m.upload_date || new Date().toISOString(),
          total_chunks: m.total_chunks || 0,
          file_url: m.file_url,
          file_path: m.file_path,
        });
      }
    });

    return NextResponse.json({ documents: Array.from(map.values()) });
  } catch (error: any) {
    return NextResponse.json({ error: error.message }, { status: 500 });
  }
}

export async function DELETE(req: Request) {
  try {
    const id = new URL(req.url).searchParams.get('id');
    if (!id) {
      return NextResponse.json({ error: 'Document ID required' }, { status: 400 });
    }

    // Get file path from metadata
    const { data: docs } = await supabase
      .from('documents')
      .select('metadata')
      .eq('metadata->>document_id', id)
      .limit(1);

    const filePath = docs?.[0]?.metadata?.file_path;

    // Delete file from storage
    if (filePath) {
      await supabaseStorage.storage.from('documents').remove([filePath]);
    }

    // Delete all chunks from database
    const { error } = await supabase
      .from('documents')
      .delete()
      .eq('metadata->>document_id', id);

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ success: true, fileDeleted: !!filePath });
  } catch (error: any) {
    return NextResponse.json({ error: error.message }, { status: 500 });
  }
}

This route handles:

• GET without ID: Lists all documents (deduplicated since each document has multiple chunks)

• GET with ID: Returns document details and full text (all chunks combined)

• GET with ID and file=true: Downloads the original file from storage

• DELETE with ID: Deletes the document and its file from both storage and database

Now that your API routes are complete, let's build the user interface components, starting with the upload modal.

Step 8: Create the Upload Modal Component

The upload modal provides a user-friendly interface for selecting and uploading documents. It handles file selection, upload progress, and displays success or error messages.

Create src/app/components/UploadModal.tsx:

'use client';
import { useState, useEffect } from 'react';

interface UploadModalProps {
  isOpen: boolean;
  onClose: () => void;
  onUploadSuccess?: () => void;
}

export default function UploadModal({ isOpen, onClose, onUploadSuccess }: UploadModalProps) {
  const [file, setFile] = useState<File | null>(null);
  const [uploading, setUploading] = useState(false);
  const [message, setMessage] = useState<{ type: 'success' | 'error'; text: string } | null>(null);

  useEffect(() => {
    document.body.style.overflow = isOpen ? 'hidden' : 'unset';
    if (!isOpen) { 
      setFile(null); 
      setMessage(null); 
    }
    return () => { 
      document.body.style.overflow = 'unset'; 
    };
  }, [isOpen]);

  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    if (e.target.files && e.target.files[0]) {
      setFile(e.target.files[0]);
      setMessage(null);
    }
  };

  const handleUpload = async () => {
    if (!file) {
      setMessage({ type: 'error', text: 'Please select a file' });
      return;
    }

    setUploading(true);
    setMessage(null);

    try {
      const formData = new FormData();
      formData.append('file', file);

      const res = await fetch('/api/upload', {
        method: 'POST',
        body: formData,
      });

      const data = await res.json();

      if (data.success) {
        setMessage({
          type: 'success',
          text: `File "${data.fileName}" uploaded successfully! Processed ${data.chunks} chunks.`,
        });
        setFile(null);
        (document.getElementById('upload-file-input') as HTMLInputElement)?.setAttribute('value', '');
        setTimeout(() => { 
          onUploadSuccess?.(); 
          onClose(); 
        }, 1500);
      } else {
        setMessage({ type: 'error', text: data.error || 'Upload failed' });
      }
    } catch (error: any) {
      setMessage({ type: 'error', text: error.message || 'Upload failed' });
    } finally {
      setUploading(false);
    }
  };

  if (!isOpen) return null;

  return (
    <div
      className="fixed inset-0 z-50 flex items-center justify-center bg-black bg-opacity-75 p-4"
      onClick={onClose}
    >
      <div
        className="relative bg-white dark:bg-gray-900 rounded-lg shadow-xl w-full max-w-2xl max-h-[90vh] overflow-y-auto"
        onClick={(e) => e.stopPropagation()}
      >
        <div className="flex items-center justify-between p-6 border-b border-gray-200 dark:border-gray-800">
          <h2 className="text-2xl font-semibold text-gray-900 dark:text-gray-100">
            Upload Document
          </h2>
          <button
            onClick={onClose}
            className="p-2 text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200 rounded-lg hover:bg-gray-100 dark:hover:bg-gray-800"
            aria-label="Close"
          >
            <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
            </svg>
          </button>
        </div>

        <div className="p-6">
          <div className="mb-6">
            <label htmlFor="upload-file-input" className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
              Select a file (PDF, DOCX, or TXT)
            </label>
            <input
              id="upload-file-input"
              type="file"
              accept=".pdf,.docx,.txt"
              onChange={handleFileChange}
              className="block w-full text-sm text-gray-500
                file:mr-4 file:py-2 file:px-4
                file:rounded-lg file:border-0
                file:text-sm file:font-semibold
                file:bg-blue-50 file:text-blue-700
                hover:file:bg-blue-100
                dark:file:bg-blue-900 dark:file:text-blue-300
                dark:hover:file:bg-blue-800"
            />
          </div>

          {file && (
            <div className="mb-6 p-4 bg-gray-50 dark:bg-gray-800 rounded-lg text-sm text-gray-600 dark:text-gray-400 space-y-1">
              <p><span className="font-medium">Selected:</span> {file.name}</p>
              <p><span className="font-medium">Size:</span> {(file.size / 1024).toFixed(2)} KB</p>
              <p><span className="font-medium">Type:</span> {file.type || file.name.split('.').pop()}</p>
            </div>
          )}

          <button
            onClick={handleUpload}
            disabled={!file || uploading}
            className="w-full bg-blue-600 text-white px-6 py-3 rounded-lg hover:bg-blue-700 disabled:bg-gray-400 disabled:cursor-not-allowed font-medium"
          >
            {uploading ? 'Uploading and Processing...' : 'Upload Document'}
          </button>

          {message && (
            <div
              className={`mt-6 p-4 rounded-lg ${
                message.type === 'success'
                  ? 'bg-green-50 text-green-800 dark:bg-green-900 dark:text-green-200'
                  : 'bg-red-50 text-red-800 dark:bg-red-900 dark:text-red-200'
              }`}
            >
              {message.text}
            </div>
          )}

          <div className="mt-8 p-4 bg-blue-50 dark:bg-blue-900/20 rounded-lg text-sm">
            <p className="font-medium text-blue-900 dark:text-blue-200 mb-2">Supported: PDF, DOCX, TXT</p>
            <p className="text-blue-700 dark:text-blue-400">Files will be processed and embedded for RAG search.</p>
          </div>
        </div>
      </div>
    </div>
  );
}

This component provides a clean interface for file uploads with proper error handling and user feedback. Next, let's create the PDF viewer component for previewing documents.

Step 9: Create the PDF Viewer Modal Component

The PDF viewer modal allows users to preview PDFs and view extracted text from any document. It's particularly useful for verifying that documents were processed correctly.

Create src/app/components/PDFViewerModal.tsx:

'use client';
import { useEffect, useState } from 'react';

interface PDFViewerModalProps {
  isOpen: boolean;
  onClose: () => void;
  fileUrl: string;
  fileName: string;
  documentId?: string;
  isPDF?: boolean;
}

export default function PDFViewerModal({ 
  isOpen, 
  onClose, 
  fileUrl, 
  fileName, 
  documentId, 
  isPDF = true 
}: PDFViewerModalProps) {
  const [error, setError] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);
  const [activeTab, setActiveTab] = useState<'preview' | 'content'>('preview');
  const [text, setText] = useState<string>('');
  const [textLoading, setTextLoading] = useState(false);
  const [textError, setTextError] = useState<string | null>(null);

  useEffect(() => {
    document.body.style.overflow = isOpen ? 'hidden' : 'unset';
    if (isOpen) { 
      setError(null); 
      setLoading(true); 
      setActiveTab(isPDF ? 'preview' : 'content'); 
      setText(''); 
      setTextError(null); 
    }
    return () => { 
      document.body.style.overflow = 'unset'; 
    };
  }, [isOpen, isPDF]);

  useEffect(() => {
    if (isOpen && documentId && activeTab === 'content' && !text && !textLoading && !textError) {
      fetchDocumentText();
    }
  }, [isOpen, documentId, activeTab, text, textLoading, textError]);

  useEffect(() => {
    if (isOpen && fileUrl && isPDF) {
      fetch(fileUrl, { method: 'GET', headers: { 'Accept': 'application/json' } })
        .then(async res => {
          if (res.headers.get('content-type')?.includes('application/json')) {
            const data = await res.json();
            throw new Error(data.error || 'File not available');
          }
          if (!res.ok) throw new Error(`Failed to load: ${res.status}`);
          setLoading(false);
        })
        .catch(err => {
          setError(err.message || 'Failed to load PDF');
          setLoading(false);
        });
    } else if (isOpen && !isPDF) {
      setLoading(false);
    }
  }, [isOpen, fileUrl, isPDF]);

  const fetchDocumentText = async () => {
    if (!documentId) return;
    setTextLoading(true); 
    setTextError(null);
    try {
      const res = await fetch(`/api/documents?id=${documentId}`);
      const data = await res.json();
      if (data.error) {
        setTextError(data.error);
      } else {
        setText(data.fullText || 'No text content available');
      }
    } catch (err) {
      setTextError(err instanceof Error ? err.message : 'Failed to fetch document text');
    } finally {
      setTextLoading(false);
    }
  };

  if (!isOpen) return null;

  return (
    <div
      className="fixed inset-0 z-50 flex items-center justify-center bg-black bg-opacity-75 p-4"
      onClick={onClose}
    >
      <div
        className="relative bg-white dark:bg-gray-900 rounded-lg shadow-xl w-full max-w-6xl h-[90vh] flex flex-col"
        onClick={(e) => e.stopPropagation()}
      >
        <div className="flex flex-col border-b border-gray-200 dark:border-gray-800">
          <div className="flex items-center justify-between p-4">
            <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100 truncate flex-1 mr-4">
              {fileName}
            </h2>
            <div className="flex items-center gap-2">
              <button
                onClick={onClose}
                className="p-2 text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200 rounded-lg hover:bg-gray-100 dark:hover:bg-gray-800"
                aria-label="Close"
              >
                <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
                </svg>
              </button>
            </div>
          </div>

          {isPDF && (
            <div className="flex border-t border-gray-200 dark:border-gray-800">
              {(['preview', 'content'] as const).map(tab => (
                <button 
                  key={tab} 
                  onClick={() => setActiveTab(tab)} 
                  className={`flex-1 px-4 py-3 text-sm font-medium transition-colors ${
                    activeTab === tab 
                      ? 'text-blue-600 dark:text-blue-400 border-b-2 border-blue-600 dark:border-blue-400 bg-blue-50 dark:bg-blue-900/20' 
                      : 'text-gray-500 dark:text-gray-400 hover:text-gray-700 dark:hover:text-gray-300 hover:bg-gray-50 dark:hover:bg-gray-800'
                  }`}
                >
                  {tab.charAt(0).toUpperCase() + tab.slice(1)}
                </button>
              ))}
            </div>
          )}
        </div>

        <div className="flex-1 overflow-hidden">
          {isPDF && activeTab === 'preview' && (
            <div className="h-full overflow-hidden">
              {error ? (
                <div className="flex flex-col items-center justify-center h-full p-8">
                  <div className="bg-yellow-50 dark:bg-yellow-900/20 border border-yellow-200 dark:border-yellow-800 rounded-lg p-6 max-w-md">
                    <h3 className="text-lg font-semibold text-yellow-800 dark:text-yellow-200 mb-2">
                      PDF File Not Available
                    </h3>
                    <p className="text-yellow-700 dark:text-yellow-300 mb-4">{error}</p>
                    {documentId && (
                      <button 
                        onClick={() => setActiveTab('content')} 
                        className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 font-medium"
                      >
                        View Extracted Text Instead
                      </button>
                    )}
                  </div>
                </div>
              ) : loading ? (
                <div className="flex items-center justify-center h-full">
                  <p className="text-gray-500 dark:text-gray-400">Loading PDF...</p>
                </div>
              ) : (
                <iframe
                  src={`${fileUrl}${fileUrl.includes('?') ? '&' : '?'}view=true#toolbar=1&navpanes=0&scrollbar=1`}
                  className="w-full h-full border-0"
                  title={fileName}
                  allow="fullscreen"
                  onError={() => setError('Failed to load PDF')}
                />
              )}
            </div>
          )}

          {(!isPDF || activeTab === 'content') && (
            <div className="h-full overflow-auto p-6">
              {textLoading ? (
                <div className="flex items-center justify-center h-full">
                  <p className="text-gray-500 dark:text-gray-400">Loading...</p>
                </div>
              ) : textError ? (
                <div className="bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg p-4">
                  <p className="text-red-800 dark:text-red-200">Error: {textError}</p>
                </div>
              ) : (
                <div className="space-y-4">
                  <p className="text-sm text-gray-500 dark:text-gray-400">
                    Formatting may be inconsistent from source.
                  </p>
                  <pre className="whitespace-pre-wrap text-sm text-gray-800 dark:text-gray-200 font-mono bg-gray-50 dark:bg-gray-800 p-4 rounded-lg">
                    {text || 'No text content available'}
                  </pre>
                </div>
              )}
            </div>
          )}
        </div>
      </div>
    </div>
  );
}

This component provides a full-screen modal for viewing PDFs and extracted text, with tabs to switch between preview and text content. Now let's create a simple navigation component to tie everything together.

Step 10: Create the Navigation Component

The navigation component provides easy access to the Search and Documents pages. It highlights the current page and provides a clean, consistent navigation experience.

Create src/app/components/Navigation.tsx:

'use client';
import Link from 'next/link';
import { usePathname } from 'next/navigation';

export default function Navigation() {
  const pathname = usePathname();

  const navItems = [
    { href: '/', label: 'Search' },
    { href: '/documents', label: 'Documents' },
  ];

  return (
    <nav className="border-b border-gray-200 dark:border-gray-800 mb-8">
      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
        <div className="flex space-x-8">
          {navItems.map((item) => (
            <Link
              key={item.href}
              href={item.href}
              className={`py-4 px-1 border-b-2 font-medium text-sm ${
                pathname === item.href
                  ? 'border-blue-500 text-blue-600 dark:text-blue-400'
                  : 'border-transparent text-gray-500 hover:text-gray-700 hover:border-gray-300 dark:text-gray-400 dark:hover:text-gray-300'
              }`}
            >
              {item.label}
            </Link>
          ))}
        </div>
      </div>
    </nav>
  );
}

With navigation in place, let's create the main search page where users can query their documents.

Step 11: Create the Home Page (Search Interface)

The search page is the main interface where users ask questions about their uploaded documents. It displays the AI-generated answers along with source citations, allowing users to verify the information.

Update src/app/page.tsx:

'use client';
import { useState } from 'react';
import Navigation from './components/Navigation';

export default function Home() {
  const [query, setQuery] = useState('');
  const [answer, setAnswer] = useState('');
  const [loading, setLoading] = useState(false);
  const [sources, setSources] = useState<any[]>([]);

  const handleSearch = async () => {
    if (!query.trim()) return;
    setLoading(true); 
    setAnswer(''); 
    setSources([]);
    try {
      const res = await fetch('/api/search', { 
        method: 'POST', 
        headers: { 'Content-Type': 'application/json' }, 
        body: JSON.stringify({ query }) 
      });
      const data = await res.json();
      if (data.error) {
        setAnswer(`Error: ${data.error}`);
      } else { 
        setAnswer(data.answer || 'No answer generated'); 
        setSources(data.sources || []); 
      }
    } catch (error: any) {
      setAnswer(`Error: ${error.message}`);
    } finally {
      setLoading(false);
    }
  };

  const handleKeyPress = (e: React.KeyboardEvent) => {
    if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
      handleSearch();
    }
  };

  return (
    <div className="min-h-screen">
      <Navigation />
      <main className="max-w-4xl mx-auto p-8">
        <h1 className="text-3xl font-bold mb-6">RAG Search</h1>

        <div className="bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-800 rounded-lg p-6 shadow-sm mb-6">
          <textarea 
            className="w-full p-4 border border-gray-300 dark:border-gray-700 rounded-lg shadow-sm bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100 resize-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
            placeholder="Ask a question about your uploaded documents..."
            value={query}
            onChange={(e) => setQuery(e.target.value)}
            onKeyDown={handleKeyPress}
            rows={4}
          />
          <button 
            onClick={handleSearch}
            className="mt-4 bg-blue-600 text-white px-8 py-3 rounded-lg hover:bg-blue-700 disabled:bg-gray-400 disabled:cursor-not-allowed font-medium"
            disabled={loading || !query.trim()}
          >
            {loading ? 'Searching...' : 'Search'}
          </button>
          <p className="mt-2 text-sm text-gray-500 dark:text-gray-400">
            Press Cmd/Ctrl + Enter to search
          </p>
        </div>

        {answer && (
          <div className="bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-800 rounded-lg p-6 shadow-sm mb-6">
            <h2 className="text-xl font-semibold mb-3">Answer:</h2>
            <p className="text-gray-800 dark:text-gray-200 leading-relaxed whitespace-pre-wrap">
              {answer}
            </p>
          </div>
        )}

        {sources && sources.length > 0 && (
          <div className="bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-800 rounded-lg p-6 shadow-sm">
            <h2 className="text-xl font-semibold mb-3">Sources ({sources.length}):</h2>
            <div className="space-y-3">
              {sources.map((source, index) => (
                <div
                  key={index}
                  className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700"
                >
                  <p className="text-sm text-gray-600 dark:text-gray-400 mb-1">
                    <span className="font-medium">Source:</span>{' '}
                    {source.metadata?.source || source.metadata?.file_name || 'Unknown'}
                  </p>
                  <p className="text-sm text-gray-800 dark:text-gray-200 line-clamp-3">
                    {source.content}
                  </p>
                </div>
              ))}
            </div>
          </div>
        )}
      </main>
    </div>
  );
}

This page provides a clean search interface with a textarea for queries, a search button, and sections to display answers and source citations. The sources section helps users verify where the information came from, which is crucial for trust and accuracy. Now let's create the documents management page.

Step 12: Create the Documents Page

The documents page serves as your document library. It displays all uploaded documents in a table format, shows metadata like file size and chunk count, and provides actions to preview, download, or delete documents. This page is essential for managing your document collection and verifying uploads.

Create src/app/documents/page.tsx:

'use client';
import { useState, useEffect } from 'react';
import Navigation from '../components/Navigation';
import PDFViewerModal from '../components/PDFViewerModal';
import UploadModal from '../components/UploadModal';

interface Document {
  id: string;
  file_name: string;
  file_type: string;
  file_size: number;
  upload_date: string;
  total_chunks: number;
  file_url?: string;
  file_path?: string;
}

export default function DocumentsPage() {
  const [documents, setDocuments] = useState<Document[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const [showPDFModal, setShowPDFModal] = useState(false);
  const [selectedPDF, setSelectedPDF] = useState<{ url: string; name: string; id?: string; isPDF?: boolean } | null>(null);
  const [deletingId, setDeletingId] = useState<string | null>(null);
  const [showUploadModal, setShowUploadModal] = useState(false);

  useEffect(() => {
    fetchDocuments();
  }, []);

  const fetchDocuments = async () => {
    try {
      setLoading(true);
      const res = await fetch('/api/documents');
      const data = await res.json();
      if (data.error) {
        setError(data.error);
      } else {
        setDocuments(data.documents || []);
      }
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Failed to fetch documents');
    } finally {
      setLoading(false);
    }
  };

  const formatDate = (s: string) => {
    try {
      const d = new Date(s);
      return isNaN(d.getTime()) 
        ? s 
        : d.toLocaleString('en-US', { 
            year: 'numeric', 
            month: 'short', 
            day: 'numeric', 
            hour: '2-digit', 
            minute: '2-digit', 
            hour12: true 
          });
    } catch { 
      return s; 
    }
  };

  const formatFileSize = (b: number) => 
    b < 1024 
      ? `${b} B` 
      : b < 1024 * 1024 
        ? `${(b / 1024).toFixed(2)} KB` 
        : `${(b / (1024 * 1024)).toFixed(2)} MB`;

  const handleDelete = async (id: string, name: string) => {
    if (!confirm(`Delete "${name}"? This will permanently delete the document, embeddings, and file.`)) {
      return;
    }
    setDeletingId(id);
    try {
      const res = await fetch(`/api/documents?id=${id}`, { method: 'DELETE' });
      const data = await res.json();
      if (data.error) {
        alert(`Error: ${data.error}`);
      } else {
        setDocuments(documents.filter(doc => doc.id !== id));
      }
    } catch (err) {
      alert(err instanceof Error ? err.message : 'Failed to delete');
    } finally {
      setDeletingId(null);
    }
  };

  return (
    <div className="min-h-screen">
      <Navigation />
      <main className="max-w-7xl mx-auto p-8">
        <div className="flex items-center justify-between mb-6">
          <h1 className="text-3xl font-bold">Documents</h1>
          <button
            onClick={() => setShowUploadModal(true)}
            className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 font-medium"
          >
            Upload Document
          </button>
        </div>

        {loading ? (
          <div className="text-center py-12">
            <p className="text-gray-500 dark:text-gray-400">Loading documents...</p>
          </div>
        ) : error ? (
          <div className="bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg p-4">
            <p className="text-red-800 dark:text-red-200">Error: {error}</p>
          </div>
        ) : documents.length === 0 ? (
          <div className="bg-gray-50 dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg p-12 text-center">
            <p className="text-gray-500 dark:text-gray-400 mb-4">No documents uploaded yet.</p>
            <button
              onClick={() => setShowUploadModal(true)}
              className="text-blue-600 dark:text-blue-400 hover:underline font-medium"
            >
              Upload your first document
            </button>
          </div>
        ) : (
          <div className="bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-800 rounded-lg shadow-sm overflow-hidden">
            <div className="overflow-x-auto">
              <table className="min-w-full divide-y divide-gray-200 dark:divide-gray-800">
                <thead className="bg-gray-50 dark:bg-gray-800">
                  <tr>
                    <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
                      File Name
                    </th>
                    <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
                      Type
                    </th>
                    <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
                      Size
                    </th>
                    <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
                      Chunks
                    </th>
                    <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
                      Upload Date
                    </th>
                    <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
                      Actions
                    </th>
                  </tr>
                </thead>
                <tbody className="bg-white dark:bg-gray-900 divide-y divide-gray-200 dark:divide-gray-800">
                  {documents.map((doc) => (
                    <tr key={doc.id} className="hover:bg-gray-50 dark:hover:bg-gray-800">
                      <td className="px-6 py-4 whitespace-nowrap">
                        <div className="text-sm font-medium text-gray-900 dark:text-gray-100">
                          {doc.file_name}
                        </div>
                      </td>
                      <td className="px-6 py-4 whitespace-nowrap">
                        <span className="px-2 inline-flex text-xs leading-5 font-semibold rounded-full bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-200">
                          {doc.file_type || 'unknown'}
                        </span>
                      </td>
                      <td className="px-6 py-4 whitespace-nowrap text-sm text-gray-500 dark:text-gray-400">
                        {formatFileSize(doc.file_size)}
                      </td>
                      <td className="px-6 py-4 whitespace-nowrap text-sm text-gray-500 dark:text-gray-400">
                        {doc.total_chunks}
                      </td>
                      <td className="px-6 py-4 whitespace-nowrap text-sm text-gray-500 dark:text-gray-400">
                        {formatDate(doc.upload_date)}
                      </td>
                      <td className="px-6 py-4 whitespace-nowrap text-sm font-medium">
                        <div className="flex gap-3 items-center">
                          {doc.file_name.toLowerCase().endsWith('.pdf') ? (
                            <button 
                              onClick={() => {
                                const pdfUrl = doc.file_url 
                                  ? `${doc.file_url}?view=true` 
                                  : `/api/documents?id=${doc.id}&file=true&view=true`;
                                setSelectedPDF({ url: pdfUrl, name: doc.file_name, id: doc.id });
                                setShowPDFModal(true);
                              }} 
                              className="text-blue-600 hover:text-blue-900 dark:text-blue-400 dark:hover:text-blue-300"
                            >
                              Preview
                            </button>
                          ) : (
                            <>
                              <button 
                                onClick={() => {
                                  setSelectedPDF({ 
                                    url: doc.file_url || `/api/documents?id=${doc.id}&file=true`, 
                                    name: doc.file_name, 
                                    id: doc.id, 
                                    isPDF: false 
                                  });
                                  setShowPDFModal(true);
                                }} 
                                className="text-blue-600 hover:text-blue-900 dark:text-blue-400 dark:hover:text-blue-300"
                              >
                                View
                              </button>
                              {(doc.file_url || doc.file_path) && (
                                <a 
                                  href={doc.file_url || `/api/documents?id=${doc.id}&file=true`} 
                                  download={doc.file_name}
                                  className="text-green-600 hover:text-green-900 dark:text-green-400 dark:hover:text-green-300" 
                                  target="_blank" 
                                  rel="noopener noreferrer"
                                >
                                  Download
                                </a>
                              )}
                            </>
                          )}
                          <button 
                            onClick={() => handleDelete(doc.id, doc.file_name)} 
                            disabled={deletingId === doc.id}
                            className="text-red-600 hover:text-red-900 dark:text-red-400 dark:hover:text-red-300 disabled:opacity-50 disabled:cursor-not-allowed"
                          >
                            {deletingId === doc.id ? 'Deleting...' : 'Delete'}
                          </button>
                        </div>
                      </td>
                    </tr>
                  ))}
                </tbody>
              </table>
            </div>
          </div>
        )}

        {selectedPDF && (
          <PDFViewerModal 
            isOpen={showPDFModal} 
            onClose={() => { 
              setShowPDFModal(false); 
              setSelectedPDF(null); 
            }}
            fileUrl={selectedPDF.url} 
            fileName={selectedPDF.name} 
            documentId={selectedPDF.id} 
            isPDF={selectedPDF.isPDF !== false} 
          />
        )}
        <UploadModal 
          isOpen={showUploadModal} 
          onClose={() => setShowUploadModal(false)} 
          onUploadSuccess={fetchDocuments} 
        />
      </main>
    </div>
  );
}

This page provides a comprehensive document management interface with a table showing all documents, their metadata, and action buttons for preview, download, and deletion. The page automatically refreshes after uploads and handles loading and error states gracefully.

Now that all your components and pages are built, let's test the complete application.

Step 13: Test Your Application

Start your development server:

npm run dev

Open http://localhost:3000 in your browser.

Test the Upload Flow

1. Navigate to the Documents page

2. Click "Upload Document"

3. Select a PDF, DOCX, or TXT file

4. Wait for the upload and processing to complete (this may take a moment as embeddings are generated)

5. You should see your document in the list with its metadata:

Test the Search Flow

1. Navigate to the Search page (or click "Search" in the navigation)

2. Make sure you've uploaded at least one document first

3. Type a question about your uploaded document (for example, "What is this document about?" or ask about specific content)

4. Click "Search" or press Cmd/Ctrl + Enter

5. You should see an AI-generated answer with source citations showing which document chunks were used

Once the embedding is done, you can navigate to search and look for the sample test command based on the documents you have uploaded. You can also check the source from which the search results were pulled.

Test Document Management

1. On the Documents page, click "Preview" or "View" on a document

2. Try downloading a document

3. Test deleting a document (be careful - this is permanent)

If everything works correctly, you're ready to deploy your application!

Step 14: Deploy Your Application

Deploy to Vercel

Vercel is the easiest way to deploy Next.js applications and is made by the creators of Next.js:

To get started, you’ll need to push your code to GitHub. So go ahead and create a repository and push your code.

Then go to vercel.com and sign in with your GitHub account. Click "New Project" and import your GitHub repository.

Add your environment variables in the project settings:

• NEXT_PUBLIC_SUPABASE_URL

• NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY

• SUPABASE_SERVICE_ROLE_KEY

• OPENAI_API_KEY

Then click "Deploy", and your application will be live in minutes! Vercel automatically builds and deploys your Next.js application, and you'll get a URL like your-app.vercel.app.

Important Deployment Notes

• Make sure all environment variables are set in your Vercel project settings

• The service role key is required for file uploads to work

• Supabase Storage bucket should be accessible (public or with proper RLS policies)

• Your OpenAI API key should have sufficient credits

How RAG Search Works

Your application uses the RAG (Retrieval-Augmented Generation) pattern. This combines information retrieval with AI text generation. Here's how it works step by step:

1. Document processing: When you upload a document, it's split into chunks. These are typically 800 characters each with 100-character overlap. Each chunk gets an embedding. This is a 1536-dimensional vector that represents its semantic meaning.

2. Storage: Embeddings are stored in a vector database. This is PostgreSQL with the pgvector extension. They're stored alongside the original text chunks. The original files are stored in Supabase Storage.

3. Query processing: When you search, your query is converted into an embedding. It uses the same model that processed the documents. This ensures the query and documents are in the same "vector space."

4. Similarity search: The system finds the most similar document chunks. It uses cosine similarity on the embeddings. Cosine similarity measures the angle between vectors. Smaller angles mean more similar content, even if the exact words differ.

5. Answer generation: The retrieved chunks are used as context for an AI model. This model is GPT-4o-mini. It generates an accurate answer. The system prompt instructs the AI to only answer based on the provided context. This ensures accuracy.

This approach gives you several benefits.

First, you get accuracy. Answers are based on your actual documents, not just the AI's training data. Second, you get transparency. You can see which document chunks were used to generate each answer. Third, you get efficiency. Only relevant chunks are used, which reduces token usage and costs. Finally, you get up-to-date information. You can update your knowledge base by uploading new documents without retraining the AI.

Troubleshooting Common Issues

"Storage RLS error" when uploading

This means your SUPABASE_SERVICE_ROLE_KEY is not set or incorrect. Make sure the key is in your .env.local file for local development. Also make sure you're using the service role key, not the anon key. Finally, make sure the key is correctly set in your deployment environment, such as Vercel.

"Failed to extract text from file"

Make sure your file is a valid PDF, DOCX, or TXT file. Check that the file isn't corrupted. For PDFs, ensure they contain extractable text. Scanned PDFs with only images won't work without OCR.

"No answer generated"

Make sure you've uploaded at least one document. Try a different query that's more likely to match your documents. Check that embeddings were successfully created. You can verify this in your Supabase database.

Vector similarity search not working

Ensure the vector extension is enabled in Supabase. You can do this by running CREATE EXTENSION IF NOT EXISTS vector;. Verify the match_documents function exists in your database. You can check this in the SQL Editor. Check that embeddings are being stored correctly. They should be JSON strings in the embedding column.

Slow search or upload times

Large documents take longer to process. This is because more chunks mean more embedding API calls. Consider reducing chunk size or processing documents in batches. Also check your OpenAI API rate limits.

Next Steps

Now that you have a working RAG search application, you can extend it with additional features. Here are some examples of useful features you could add:

• You can add more file types by extending the text extraction to support Markdown, HTML, or other formats.

• You can improve chunking by experimenting with different chunk sizes, overlap strategies, or semantic chunking.

• You can add authentication to protect your documents with user authentication using Supabase Auth.

• You can enhance the UI by adding features like search history, document tags, or advanced filters.

• You can optimize performance by adding caching, pagination, or streaming responses.

• You can add filters to allow users to search within specific documents or date ranges.

• Finally, you can improve search by adding hybrid search, which combines keyword and semantic search, or reranking.

Conclusion

You've built a complete RAG search application from scratch. This application demonstrates modern web development with Next.js and TypeScript. It shows vector database operations with Supabase and pgvector. It demonstrates AI integration with OpenAI embeddings and chat completions. It includes file handling and storage with Supabase Storage. Finally, it features a production-ready user interface with Tailwind CSS.

The RAG pattern you've implemented is used by many production applications. These include chatbots, knowledge bases, document search systems, and AI assistants. You now have the foundation to build more advanced features on top of this.

The skills you've learned are highly valuable in today's AI-driven development landscape. You've learned to work with embeddings, vector databases, and the RAG pattern. You can apply these concepts to build intelligent search systems, document Q&A applications, or AI-powered knowledge bases.

In this article, you’ll learn what the tailwind-sidebar NPM package is, how it works internally, and how to install and configure it in a real project. We’ll walk through setting up a responsive sidebar using Tailwind CSS, explore its key features with practical examples, and see how you can customize and control the sidebar behavior to fit different layouts and screen sizes.

If you’re building a React or Next.js application and want a lightweight yet powerful sidebar solution, tailwind-sidebar is an excellent choice.

Table of Contents

• Prerequisites

• Introduction to the tailwind-sidebar NPM Package

• Why Choose Tailwind Sidebar?

• How to Get Started with Tailwind Sidebar

• Features of Tailwind Sidebar:

• Wrapping Up

Prerequisites

• Basic knowledge of JavaScript (ES6+)

• Familiarity with React fundamentals (components, props, JSX)

• Basic understanding of Next.js project structure and routing

• Experience using npm or yarn for package installation

• Working knowledge of Tailwind CSS

Introduction to the tailwind-sidebar NPM Package

The tailwind-sidebar NPM package is a modern, developer-friendly sidebar component that’s built entirely with Tailwind CSS. It’s designed to help developers create responsive, customizable, and accessible sidebars without the overhead of heavy UI frameworks.

Understanding Tailwind Sidebar

tailwind-sidebar is a lightweight utility package designed to simplify building responsive sidebars using Tailwind CSS. Instead of manually handling sidebar state, transitions, and responsive behavior, the package provides a small JavaScript layer that works alongside Tailwind’s utility classes.

At its core, the package toggles Tailwind classes to control whether the sidebar is open or closed. This makes it framework-agnostic - it works with plain HTML, as well as frameworks like React, Vue, or Next.js, as long as Tailwind CSS is available.

Because it relies on Tailwind utilities rather than custom CSS, the sidebar stays easy to customize, extend, and maintain.

What is Tailwind CSS?

Tailwind CSS is a utility-first CSS framework that lets you build modern, responsive user interfaces directly in your markup. Instead of predefined components, Tailwind provides low-level utility classes that give you full design control without leaving your HTML.

Tailwind Sidebar is built on top of Tailwind CSS, offering a clean, flexible, and highly customizable sidebar solution for modern web applications.

Why Choose Tailwind Sidebar?

Optimized Performance

Tailwind Sidebar relies on utility classes instead of heavy JavaScript logic. This means that it delivers fast load times and smooth interactions, and is ideal for performance-critical applications.

Developer-Friendly

It doesn’t have any complex configuration or component APIs. If you know Tailwind CSS, you already know how to customize the sidebar.

Easy Maintenance

With a simple and predictable structure, updates and custom changes are straightforward, making it suitable for both small projects and large-scale applications.

Growing Tailwind Community

Tailwind CSS has a massive and active community. This means better tooling, regular updates, and a wealth of learning resources to support your development workflow.

How to Get Started with Tailwind Sidebar

This section will walk you through installing and setting up tailwind-sidebar in a React and Next.js application. You’ll learn how to add a sidebar, create menus, add a logo, and customize navigation.

Step 1: Install tailwind-sidebar

To begin, you’ll need to install tailwind Sidebar into your React and Next.js project. You can do this using either npm or yarn.

Using npm:

npm i tailwind-sidebar

Using yarn:

yarn add tailwind-sidebar

This will add tailwind-sidebar and its dependencies to your project.

Step 2: Import the Tailwind Sidebar Component

Once the package is installed, you can import the necessary components from tailwind-sidebar into your project. These components will allow you to customize the sidebar with menus, submenus, and even a logo.

import {

  AMSidebar,

  AMMenuItem,

  AMMenu,

  AMSubmenu,

  AMLogo,

} from "tailwind-sidebar";

Adding Styles to Tailwind Sidebar

To use the default styles of tailwind-sidebar, you need to import its CSS file at the top of your project:

import "tailwind-sidebar/styles.css";

Step 3: Routing Setup for React and Next.Js

To enable navigation inside tailwind-sidebar components like AMMenuItem or AMLogo, you need to pass a link component from either react-router or next/link using the component prop inside the corresponding component, like what’s shown in the below example:

If you're using React:

import { Link } from "react-router-dom";

<AMSidebar width={"270px"}>

     <AMLogo img="https://adminmart.com/wp-content/uploads/2024/03/logo-admin-mart-news.png"
        component={Link}
        href="/"
      >
        Adminmart

      </AMLogo>
      <AMMenu subHeading="HOME">
        <AMMenuItem
         icon={<Home />}
          link="/"  // Passing link to component for routing
          badge={true}
          badgeType="default"
          badgeColor={"bg-secondary"}
          isSelected={true}
        >
          {/* text for your link */}
          Link Text
        </AMMenuItem>
      </AMMenu>
   </AMSidebar>

And if you're using Next.js:

import  Link  from "next/link";<AMSidebar width={"270px"}>
  <AMLogo img="https://adminmart.com/wp-content/uploads/2024/03/logo-admin-mart-news.png"
        component={Link} // Passing link to component for routing
        href="/"
      >
        Adminmart
      </AMLogo>
        AdminMart
      </Logo>
      <AMMenu subHeading="HOME">
         <AMMenuItem
          icon={<Home />}
          link="/tes"
          component={Link}
          isSelected={true}
        >
           Link Text {/* text for your link */}
        </AMMenuItem>
      </AMMenu>
    </AMSidebar>

Step 4: Initializing the Sidebar

Now we’ll set up the AMSidebar component in your application. You can set the width of the sidebar using the width prop. Here’s a simple example:

<AMSidebar width={"270px"}> // pass the width you want your sidebar to have

{/* Sidebar Content Goes Here */}

</AMSidebar>

This initializes the sidebar with a width of 270px. You can adjust this width based on your design requirements.

Step 5: Adding a Logo to the Sidebar

You can add a logo inside the sidebar by using the AMLogo component. To do so, you can provide an img prop to link to a CDN logo image. You can also make the logo clickable by passing a navigation link using the component and href props. Here’s how you can include a logo:

<AMSidebar width={"270px"}>

<AMLogo img="https://adminmart.com/wp-content/uploads/2024/03/logo-admin-mart-news.png"
component={Link}
href="/" 
>        
Adminmart
</AMLogo>

</AMSidebar>

In this example, we’ve added a logo from a CDN using the img prop, used the component prop to pass the Link, and set the navigation path to (/) homepage using the href prop and set the text “AdminMart” as the name of the application.

Step 6: Creating a Menu Inside the Sidebar

Now let’s create a menu inside the sidebar using the AMMenu component. You can specify a submenu heading using the subHeading prop. Inside the AMMenu, you can add AMMenuItem components for each item.

You can also provide a link prop along with the component prop to the AMMenuItem to turn the item into a clickable link.

Here’s how you can structure the menu:

<AMSidebar
 width={"270px"}>
  <AMMenu subHeading="HOME">
  <AMMenuItem  component={Link}  link="/"  badge=”true”  isSelected={true} >
      Modern
    </AMMenuItem>
    <AMMenuItem>eCommerce</AMMenuItem>
    <AMMenuItem>Analytical</AMMenuItem>
  </AMMenu>
</AMSidebar>

In this example:

• We’ve added a AMMenu with the heading “HOME”.

• The first AMMenuItem has a link prop, so clicking it will navigate to the homepage (/).

• The second and third AMMenuItem components are simple text items without links.

You can use the badge="true" prop to indicate a badge or notification on the AMMenuItem. The isSelected={true} prop marks this menu item as currently selected or active (though you can customize this feature according to your needs).

Step 7: Adding Submenus (Optional)

To add submenus inside the main menu, use the AMSubmenu component. The AMSubmenu can be nested inside the AMMenu component and contains its own set of AMMenuItem. Use the title prop to set the submenu heading

Here’s an example of adding a submenu:

<AMSidebar  width={"270px"}>
    <AMMenu subHeading="SERVICES">
      <AMMenuItem  component={Link}   link="/web-development">Web Development</AMMenuItem>
      <AMMenuItem component={Link}  link="/seo-services">SEO Services</AMMenuItem>
      <AMSubmenu title="Marketing">
            <AMMenuItem component={Link}  link="/digital-marketing">Digital Marketing</AMMenuItem>
           <AMMenuItem component={Link}  link="/content-marketing">Content Marketing</AMMenuItem>
      </AMSubmenu>
  </AMMenu>
</AMSidebar>

In this example:

• A submenu under the "Marketing" heading is added inside the "SERVICES" menu.

• The submenu contains two AMMenuItem with links to different service pages.

Features of Tailwind Sidebar:

Utility-First & Lightweight

Tailwind Sidebar is built entirely using Tailwind CSS utility classes. This means there’s no heavy JavaScript logic or extra styling framework, keeping your bundle size small and performance fast.

Code Example:

<AMSidebar width="260px" className="bg-gray-900 text-white">
     <AMMenu>
           <AMMenuItem>Dashboard</AMMenuItem>
      </AMMenu>
 </AMSidebar>

What’s going on here:

• bg-gray-900 text-white: Applies a dark background and white text directly via Tailwind classes (no separate CSS file).

• width="260px": The component prop sets the sidebar width. Here, it shows how Tailwind utilities combine with props to control layout.

Because all spacing and colors are from Tailwind classes, you don’t need additional custom styles.

Fully Responsive Design

The sidebar adapts seamlessly to different screen sizes. Whether you’re building for desktop, tablet, or mobile, Tailwind Sidebar ensures a smooth and consistent navigation experience.

Example usage:

<AMSidebar width="260px" className="hidden md:block">
  <AMMenu>
           <AMMenuItem>Home</AMMenuItem>
      </AMMenu>
</AMSidebar>

What’s going on here:

• hidden md:block: Uses Tailwind responsive utility classes to hide the component (hidden) on mobile screens and show it starting at the md breakpoint (md:block).

This pattern is Tailwind’s common way of controlling visibility across breakpoints without media queries.

Highly Customizable

Tailwind Sidebar allows full customization of colors, hover states, spacing, and typography directly through Tailwind classes. You can customize layout and animations – all without touching custom CSS files.

Example usage:

 <AMMenuItem className="hover:bg-blue-600 rounded-lg px-4 py-2”>
      Analytics
  </AMMenuItem>

What’s going on here:

• hover:bg-blue-600: When you hover the menu item, the background changes to blue, purely via Tailwind.

• rounded-lg: Adds rounded corners.

• px-4 py-2: Controls horizontal (px) and vertical (py) padding to adjust spacing.

Together, these utilities show how Tailwind gives control of design details directly at the HTML/JSX level.

Integration with React & Next.Js:

Tailwind Sidebar seamlessly integrates with both React & Next.js, offering a familiar and efficient development experience.

The sidebar works natively with both React Router and Next.js routing by passing the Link component.

React Example
{
  /* if you are using react then import link from  */
}

import { Link } from "react-router-dom";
<AMMenuItem component={Link} link="/dashboard">
            Dashboard 
</AMMenuItem>

Next.js Example
{
  /* if you are using nextjs then import link from  */
}

import Link from "next/link";

<AMMenuItem component={Link} link="/dashboard">
         Dashboard
</AMMenuItem>

What’s going on here:

• component={Link} link="/dashboard": Shows how you pass your framework’s routing component into AMMenuItem, turning it into a real navigational link.

This means Tailwind Sidebar adapts to both React Router and Next.js routing without boilerplate.

Menu & Submenu Support

Organize your navigation with:

• Main menu items

• Nested submenus

This makes it easy to manage complex navigation structures while keeping the UI clean and intuitive.

Example usage:

<AMMenu subHeading="MANAGEMENT">
             <AMMenuItem>Users</AMMenuItem>
                <AMSubmenu title="Reports">
                   <AMMenuItem>Sales</AMMenuItem>
                      <AMMenuItem>Revenue</AMMenuItem>
                    </AMSubmenu>
</AMMenu>

What’s going on here:

• subHeading="SERVICES": Adds a labeled grouping for menu items.

• The nested <AMSubmenu> demonstrates how nested navigation is rendered and structured in JSX.

This example clearly shows hierarchical menus without additional CSS – structure and Tailwind classes handle layout.

Icon Support

The sidebar comes with built-in support for icons, allowing developers to enhance the visual appeal and usability of their application. Developers can use any icon library and provide the icon component.

Example using lucide-react:

import { Home } from "lucide-react";

<AMMenuItem icon={<Home size={18} />}>
     Home
</AMMenuItem>

What’s going on here:

• icon={<Home size={18} />}: Here, an icon component is passed as a prop.

• You control the size directly via the icon library (Lucide here) and Tailwind handles spacing/placement next to text.

This illustrates how icons and text combine in the sidebar component.

Smooth Transitions

Tailwind Sidebar provides built-in animation support through the animation prop. When enabled, menu items and submenus animate smoothly, improving the overall user experience without requiring custom CSS or JavaScript.

Example Usage:

<AMSidebar width="270px" animation={true}>
           <AMMenu subHeading="SETTINGS">
                  <AMMenuItem>Profile</AMMenuItem>
                  <AMMenuItem>Security</AMMenuItem>
             </AMMenu>
</AMSidebar>

What’s going on here:

• animation={true}: Enables built-in animation support.

The example shows how adding this prop triggers smooth transitions defined by the component itself (still relying on Tailwind utilities internally). You don’t have to write CSS keyframes or transition utilities manually.

Wrapping Up

You have now successfully integrated a fully functional sidebar in your React and Next.js application using tailwind-sidebar. You can further customize the sidebar by:

• Modifying the width and design.

• Adding more submenus, menu items, or icons.

• Using links to navigate between pages.

This setup provides a flexible, responsive, and easy-to-use sidebar, which is perfect for most web applications.

If you want to see how this kind of sidebar fits into a real dashboard layout, you can explore an open-source Tailwind CSS admin template at https://tailwind-admin.com/.

Try It Out:

You can view the working demo of the tailwind-sidebar here: View Demo.

Note: in this tutorial, we utilized lucide-react to construct this sidebar. Feel free to choose an alternative library or use different icons based on your specific requirements.

Other Sidebar NPM Packages

You can also try Next.js Tailwind Sidebar – a simple and responsive sidebar built for Next.js, and React Tailwind Sidebar – a lightweight Tailwind-based sidebar for React applications.

Rate limiters enforce the responsible use of APIs by blocking requests that exceed the set usage limits.

By following along with this article, you will:

• Learn how rate limiters work

• Build an in-memory rate limiter for a Next.js pa router project

• Use Artillery to load test the rate limiter for accuracy and resilience

Here’s What We’ll Cover:

1. Benefits of Rate Limiters

2. How Rate Limiters Work

3. Rate Limiting Algorithms

4. How to Build an In-Memory Rate Limiter

   • How The In-Memory Rate Limiter Works

   • The Request Handler

5. The Front End

6. How to Load Test the Rate Limiter for Resilience with Artillery

   • The Load Test Configuration

   • Run the Load Test

   • Review the Results

7. Conclusion

To get the most out of this article, you should have experience in building APIs with Next.js pages router, Express, or any other Node.js backend framework that uses middlewares.

Benefits of Rate Limiters

Rate limiters control how many requests are allowed within a given time window. They have several benefits you should know about if you’re considering using them.

First, they help prevent the abuse of web servers. Rate limiters guard web servers from overuse that needlessly increases their load. They block excessive requests from Denial of Service (DoS) attacks from bots so that the web service doesn’t crash from unnecessary overload and can continue to be available to legitimate users.

They also help manage the cost of using external APIs. Some API endpoints make requests to external APIs to complete their operations – for example, API endpoints that send emails through an email service provider. When an endpoint relies on paid external APIs and user access of the endpoint is not restricted, excessive usage can lead to increased and expensive costs for the web service. Rate limiters block the excessive usage of endpoints like these, helping to keep costs to a reasonable minimum.

How Rate Limiters Work

Rate limiters work using a three-step mechanism. The process includes tracking requests from specific clients, monitoring their usage, and blocking extra requests once the threshold has been exceeded.

In more detail, rate limiters:

• Track requests: Rate limiters take note of API clients that make requests and attributes that are specific to the clients (for example, an IP address or a userId). These specific attributes are references or keys that are used to identify clients.

• Monitor usage: Depending on the rate limiting mechanism, rate limiters increase or decrease the metric that is used to determine the threshold of use. For example, within a three-hour time period, Twitter can track and increase the number of times a user makes an API request to the create tweet endpoint.

• Ensure threshold compliance: Rate limiters check the threshold of use for every request made. If it has been exceeded, it blocks the request from accessing the functionality of the API endpoint and responds with a status code of 429.

  

Rate Limiting Algorithms

You can implement rate limiting using different algorithms based on the requirements of the rate limiter. Each rate limiting algorithm has its merits and demerits. Below are some popular rate limiting algorithms you can play around with.

Fixed Window Algorithm

In the fixed window rate limiting algorithm, the number of requests made within a fixed time period is tracked and every request increases the request count tracked. If the number requests within the time frame is exceeded, any extra request that comes in within the time frame is blocked. At the end of the time period, the request count is reset and increases for every request made.

Its mechanism is easy to understand and it’s memory-efficient. Its challenge is that spikes in traffic close to the start or the end of a time window can allow more requests than permitted.

Sliding Window Algorithm

The sliding window algorithm fixes the issue with the fixed window algorithm where spikes in traffic close to the start or end of a time window can allow more requests than permitted.

It works as follows:

• It keeps a track of the timestamps of requests made in a cache.

• When there’s a new request, it removes all timestamps that are older than the start of the current time window and it appends the new request’s timestamp to the cache.

• If the count of the requests in the cache is higher than the threshold, the request is blocked. Otherwise, it’s allowed.

Although this algorithm is more accurate than the fixed window algorithm, it consumes more memory because of the storage of timestamps.

Token Bucket Algorithm

In the token bucket algorithm, a bucket that contains a predefined number of tokens is assigned to a user. Tokens are added to the bucket at a predefined rate, for example 2 tokens may be added every second.

Once the bucket is full, no more tokens are added. Each request consumes one or more tokens, and if the tokens are exhausted, requests are blocked until the bucket has tokens again.

The Token Bucket algorithm has the benefits of being memory efficient, easy to implement, and accurate enough to block extra requests even during a burst in traffic.

In this tutorial, we’ll use the fixed window algorithm to build a rate limiter. We’ll also battle-test it for resilience and accuracy using Artillery.

How to Build an In-Memory Rate Limiter

If you’re a backend developer, you may have noticed that users sometimes abuse the reset password API endpoint in your Next.js application. This is a cause for concern because the API endpoint makes a request to your email service provider to send an email and you get charged for it.

Because of this, you may want to limit the requests that users make to this endpoint so that you can prevent the abuse of the API and save costs. And that’s where a rate limiter comes in.

You can get the code for this tutorial hereis tutorial here. You can clone it, install the dependencies with npm install, and run it following the instructions in the README file. You’ll need it to follow along with the rest of this article.

I built the project using Next.js and it uses the pages router. I’ve also built the rate limiter and you can find it here. You can see how to use it in the reset password API endpoint here.

It has a user interface that you can use to test the rate limiter – but let’s dive into the code first.

How The In-Memory Rate Limiter Works

To help you better understand the rate limiter, I've created this diagram. We'll walk through what's happening after:

The src/lib/server/rate-limiter.ts file exports a function called applyRateLimiter which accepts three parameters:

• the request object

• the response object

• getOptsFn

getOptsFn is a function that accepts the request object and, when executed, returns properties specific to the request for tracking, monitoring, and blocking by the rate limiter. getOptsFn is a function and not a static object so that the specific properties of a request can be dynamically created by the request handler for each request.

src/lib/server/rate-limiter.ts also has an in-memory map called cache. cache stores the key (or unique identifier) of a request and maps it to its usage. An interval runs every minute to remove keys with expiredAt values that have passed from the cache. This helps to manage the amount of memory used by the cache.

type GetOptionsFn = (req: NextApiRequest) => {
  key: string;
  maxTries: number;
  expiresAt: Date;
};

const cache = new Map<string, Usage>();

// clear stale keys from cache every minute
setInterval(() => {
  const currentDate = new Date();
  for (const [key, usage] of cache) {
    if (!usage) continue;

    if (currentDate > usage.expiresAt) {
      cache.delete(key);
    }
  }
}, 60000);

When the rate limiter is executed, it uses the getOptsFn to generate the following from the request:

• key: The unique identifier for the request that can be used to track its usage

• maxTries: The maximum number of times a request can be made within the specified time window

• expiresAt: The expiry time of a time window

based on its content where it was created.

  const opts = getOptsFn(req);
  const usage = cache.get(opts.key);

  if (!usage) {
    cache.set(opts.key, {
      tries: 1,
      maxTries: opts.maxTries,
      expiresAt: opts.expiresAt,
    });

    return;
  }

The rate limiter then checks if the key of the request exists in the cache. If it doesn’t, it sets it in the cache, mapping it to the following values:

• tries : The number of times that the request has been made without being blocked

• maxTries: The maximum number of times that the request should be allowed within the time window without blocking

• expiresAt: The expiry time of the time window

It also allows the request to continue by exiting the rate limiter through the return statement. The values set in cache will be used to determine if and when consecutive requests with the same key should be blocked or not.

If the request’s key exists in cache, the rate limiter checks if the number of unblocked tries (usage.tries) from cache is less than the number of allowed usage tries (usage.maxTries). If it evaluates to true, it means that the request has not exceeded its maximum tries. It also checks if the expiry time of the time window stored in cache for the request has elapsed.

The request is not blocked if one of the following conditions evaluates to true:

• the request has not exceeded its maximum tries AND its time window has not elapsed

• the current time window of the request usage in cache (usage.expiresAt) has elapsed

  const currentDate = new Date();
  const retryAfter = usage.expiresAt.getTime() - currentDate.getTime();
  const timeWindowHasElapsed = retryAfter < 0
  const canProceed = usage.tries < opts.maxTries && !timeWindowHasElapsed;

  if (canProceed) {
    cache.set(opts.key, {
      ...usage,
      tries: usage.tries + 1,
    });

    return;
  }

  if (timeWindowHasElapsed) { // if usage.expiresAt has elapsed
    cache.set(opts.key, {
      tries: 1,
      maxTries: opts.maxTries,
      expiresAt: opts.expiresAt,
    });

    return;
  }

If canProceed is truthy, the rate limiter increases the number of tries (usage.tries) that the request has in the cache and then allows the request to proceed by exiting the rate limiter using the return statement. If timeWindowHasElapsed is truthy, the rate limiter resets the usage of the request in the cache using values gotten from getOptsFn and then allows the request to proceed. If both conditions are falsy, the request is blocked with a 429 response status code.

  res.setHeader("Retry-After", retryAfter/1000);
  return res.status(429).json({
    error: { message: "Too many requests" },
  });

According to REST specifications, a 429 HTTP response may include a Retry-After header to let clients know how long to wait before making a new request. The value of the Retry-After header had been calculated beforehand and is set on the response object using res.setHeader.

The Request Handler

You can find the reset password request handler in src/pages/api/reset-password-init.ts. First, it performs validation checks on the request method and body to ensure that it is fit for its operations. The validation ensures that the request is a POST request and that the request body includes an email property. It ends the request with the appropriate response code if validation fails.

  if (req.method !== "POST") {
    return res.status(405).json({
      error: { message: "Not allowed" },
    });
  }

  if (!req.body.email || typeof req.body.email != "string") {
    return res.status(400).json({
      error: { message: "'email' is required" },
    });
  }

generateOptions is the function that is eventually passed as getOptsFn to the rate limiter. The generateOptions function generates the specific properties of the request for the rate limiter. In the case of this endpoint, the properties are:

• key: A string in the format [method].[endpoint].[email]. For an email value of “Hello@me.com”, the key will be post.reset-password.hello@me.com which will be constant for every request for that email to this endpoint. This key value format makes it unique and specific to this request.

• expiresAt: The time when the time window expires. If the request is in cache, this value is ignored by the rate limiter and it uses the value in the cache instead

• maxTries: The maximum number of tries that should be allowed within the time window. If the request is in the rate limiter cache already, this value is ignored in preference of the value in cache.

  const generateOptions = function (req: NextApiRequest) {
    const now = new Date();
    const inFiveSeconds = new Date(now.getTime() + 5000);

    return {
      expiresAt: inFiveSeconds,
      key: `post.reset-password.${req.body.email.toLowerCase()}`,
      maxTries: 1,
    };
  };

For the reset password handler, requests are rate limited to one every five seconds. You can tweak the expiresAt and maxTries values to test how it works. applyRateLimiter is executed with its arguments and if it does not block the request, the handler can go on to send the mail and respond to the client.

The Front End

You can visit the user interface to test the rate limiter manually. Visit the URL shown (http://localhost:3000 by default) after you ran npm run dev. You should see the user interface shown below to test the rate limiter.

How to Load Test the Rate Limiter for Resilience with Artillery

Artillery is a tool for testing and reporting how well web applications can perform under heavy load. In this section, you will use Artillery to test how efficient and accurate the rate limiter that you built is.

To use Artillery, install it globally via the npm install -g artillery@latest command so that the artillery command can be available for use via the CLI.

The Load Test Configuration

In the loadtest folder located at the root of the project, you will find the setup.yaml file. It contains the instructions for Artillery to use to carry out the load test. The instructions tell Artillery to create virtual users that will make API requests to the application with the base URL identified by target in three phases:

• Warm up: Make API requests for a duration of ten seconds, starting from one request per second and increase it to five requests per second.

• Ramp up: After warm up, make API requests for a duration of thirty seconds, starting from five requests per second and increase it to ten requests per second.

• Spike phase: After ramp up, make API requests for a duration of twenty seconds, starting from ten requests per second and increase it to thirty requests per second.

This brings the total time of the load test to sixty seconds.

config:
  target: http://localhost:3000/api

  phases:
    - duration: 10
      arrivalRate: 1
      rampTo: 5
      name: Warm up

    - duration: 30
      arrivalRate: 5
      rampTo: 10
      name: Ramp up

    - duration: 20
      arrivalRate: 10
      rampTo: 30
      name: Spike phase

The plugins section contains instructions for extensions you can use to analyse the results from Artillery and get reports. For example, the ensure plugin contains setups that will report “OK” if at least 99% of the request responses have a latency of 100ms or less.

  plugins:
    ensure:
      thresholds:
        - http.response_time.p99: 100
        - http.response_time.p95: 75

The metrics-by-endpoint plugin (not used in this project) is another Artillery plugin that is used to display response time metrics for each URL in the test.

A scenario is a sequence of steps that describes a virtual user session in the app. Each virtual user created in phases will make an API request to the end endpoint in flow and the requests in the loop will happen or loop only once per virtual user (because the flow count has a value of 1).

scenarios:
  - flow:
      - loop:
          - post:
              url: "/reset-password-init"
              headers:
                Content-Type: "application/json"
              json:
                email: "j.doe@email.com"

        count: 1

Run the Load Test

Make sure that the application is running and run the load test with the command artillery run loadtest/setup.yaml --output loadtest/results.json from the root folder of the project. This will run the load test on the rate-limited endpoint and save the output of the results in loadtest/results.json.

Review the Results

Regardless of the of the number of requests made, the setup of our rate limiter allows only one request every five seconds. This means that the number of requests that should be allowed within a space of sixty seconds is twelve.

If you take a look at loadtest/results.json, you will see that only twelve requests had a status code of 200. If you increase the values of arrivalRate or rampTo in any or all of the phases to increase the number of requests made to the endpoint and you run the load test again, only twelve requests will still have a status code of 200. This means that our rate limiter is remaining effective and accurate even under high loads.

For latency, you should consider the report of the ensure plugin which is logged to the terminal at the end of the test. A result such as:

Checks:
ok: http.response_time.p95 < 75
ok: http.response_time.p99 < 100

means that 95% of all requests made had a latency of less than 75 milliseconds and 99% of all requests made had a latency of less than 100 milliseconds. These are good results.

Conclusion

In this article, you have learned about rate limiters, rate limiting algorithms, and how to build and use an in-memory rate limiter in Next.js.

You also got a brief introduction to load testing with Artillery. Be sure to apply what you have learned in one of your Next.js projects when you need it.

Feel free to connect with me on LinkedIn for questions or clarifications. Thank you for reading this far and I hope this helps you achieve what you intended to achieve. Don’t hesitate to share this article if you feel that it would help someone else out there. Cheers!