Deploy Next.js 15 to Cloudflare Workers: Complete Guide

Create the KV namespace for caching:

npx wrangler kv namespace create CACHE
# Copy the returned ID into wrangler.jsonc

Step 3: Environment Variables

Never commit secrets to wrangler.jsonc. Use Wrangler secrets instead:

# Add each secret interactively
npx wrangler secret put DATABASE_URL
npx wrangler secret put NEXTAUTH_SECRET

# List configured secrets
npx wrangler secret list

For local development, use .env.local:

DATABASE_URL=postgresql://user:[email protected]/db?sslmode=require
NEXTAUTH_SECRET=your-dev-secret
NEXT_PUBLIC_APP_URL=http://localhost:3000

Step 4: Database — Neon PostgreSQL

Cloudflare Workers cannot use TCP connections. You must use Neon's HTTP-based driver:

npm install @neondatabase/serverless

Basic connection:

import { neon } from "@neondatabase/serverless";

const sql = neon(process.env.DATABASE_URL!);
const users = await sql`SELECT id, name FROM users LIMIT 10`;

With Drizzle ORM (recommended for production):

// lib/db.ts
import { neon } from "@neondatabase/serverless";
import { drizzle } from "drizzle-orm/neon-http";
import * as schema from "./schema";

const sql = neon(process.env.DATABASE_URL!);
export const db = drizzle(sql, { schema });

Important: If you're using pg (node-postgres) with new Pool(...), you need to migrate to @neondatabase/serverless. Workers don't have TCP sockets.

Step 5: Local Development with Workers Runtime

Don't just run npm run dev. Test in the actual V8 isolate:

# Build Next.js
npm run build

# Build for Workers
npx @opennextjs/cloudflare build

# Run in Workers runtime (localhost:8787)
npx wrangler dev

This is critical — it catches runtime errors that don't appear in plain Node.js (e.g., TCP connections, missing Node.js APIs).

Step 6: Deploy to Production

npx @opennextjs/cloudflare build
npx wrangler deploy

Output after a successful deploy:

✅ Deployed my-nextjs-app
   https://my-nextjs-app.your-username.workers.dev

Step 7: Custom Domain

Your domain must be managed in Cloudflare DNS:

npx wrangler domains add myapp.com

Or via wrangler.jsonc:

{
  "routes": [
    {
      "pattern": "myapp.com/*",
      "zone_name": "myapp.com"
    }
  ]
}

Step 8: CI/CD with GitHub Actions

Auto-deploy on every push to main:

# .github/workflows/deploy.yml
name: Deploy to Cloudflare Workers

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - run: npx @opennextjs/cloudflare build
      - run: npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Create your token: Cloudflare Dashboard → My Profile → API Tokens → Create Token → use "Edit Cloudflare Workers" template. Add it as a GitHub Secret named CLOUDFLARE_API_TOKEN.

Performance Tips

1. Aggressive caching

// app/api/products/route.ts
export async function GET() {
  const data = await getProducts();
  return Response.json(data, {
    headers: {
      "Cache-Control": "public, s-maxage=60, stale-while-revalidate=300",
    },
  });
}

2. Cloudflare KV for session data

// Read from KV cache (~1ms) before hitting the DB
const cached = await env.CACHE.get(`session:${userId}`);
if (!cached) {
  const user = await db.query.users.findFirst({ where: eq(users.id, userId) });
  await env.CACHE.put(`session:${userId}`, JSON.stringify(user), {
    expirationTtl: 3600,
  });
}

3. Keep bundle under 10MB

• Use named imports — avoid importing entire libraries
• Analyze with @next/bundle-analyzer
• Use next/dynamic for heavy components

4. Streaming SSR for large pages

import { Suspense } from "react";

export default function DashboardPage() {
  return (
    <Suspense fallback={<Skeleton />}>
      <DataHeavyComponent />
    </Suspense>
  );
}

Common Issues

Building an MVP with Next.js? Check out why Next.js + TypeScript + Postgres is the best MVP stack — the Cloudflare Workers setup works seamlessly with this stack. Need to add a data pipeline? See our guide on building real-time data pipelines with PostgreSQL.