Search for a command to run...
Yusuf Adeyemo is a DevOps Engineer from Nigeria. He loves helping startups deliver better software and provide more control over their environment and software development process with the help of modern tools and automation.
No comments yet. Be the first to comment.
We’ve all been there. You spend hours perfectly tuning your OpenWrt configuration, setting up your captive portals, and hardening your firewall. Then, six months later, the system hangs. Why? Because
This article started from a tweet. Someone on Twitter said they "lowkey want to understand the technology behind Google Authenticator" and I dropped a quick reply - explaining that it's basically TOTP: your device and the server share a secret key, b...
Have you ever sat there waiting for your CodeBuild project to rebuild your entire Docker image... again? Even though you only changed a single line of code? Yeah, me too. And it's frustrating. Today, I'm going to show you how I reduced our Docker bui...
After you complete this article, you will have a solid understanding of: What L1, L2, and L3 constructs actually are and when to use each Why AWS created three different abstraction levels (and the hidden benefits) How to avoid the most common CDK...
On this page
After you complete this article, you will have a solid understanding of:
Why deploying Next.js SSR on Cloudflare is different from traditional hosting
The real difference between Cloudflare Pages with next-on-pages and OpenNext adapter
How the free tier's 100,000 daily requests can handle production traffic
Common deployment pitfalls that will waste hours of debugging
Which adapter to choose for your specific use case
If you've tried deploying a Next.js app to Cloudflare Pages, you've probably encountered this frustrating message:
Error: Dynamic server usage: Page couldn't be rendered statically because it used `cookies`.
Or even worse:
Error: The edge runtime does not support Node.js 'fs' module.
You can use 'fs' module only in Node.js runtime.
And then you wonder: "But I thought Cloudflare supports Next.js SSR now?"
Let me clear up this confusion once and for all.
There are two completely different approaches to deploying Next.js on Cloudflare, and choosing the wrong one will cause endless headaches.
This was the original way, and it comes with a massive limitation:
// Every server component needs this 👇
export const runtime = 'edge';
export default async function Page() {
// ❌ This will fail!
const fs = require('fs');
// ❌ This will also fail!
const bcrypt = require('bcrypt');
// ✅ Only Web APIs work
const response = await fetch('https://api.example.com');
return <div>Limited to Edge Runtime</div>;
}
Released in 2024 and now in v1.0-beta, this adapter supports the Node.js runtime:
// No runtime declaration needed! 🎉
export default async function Page() {
// ✅ This works now!
const fs = require('fs');
// ✅ This works too!
const crypto = require('crypto');
// ✅ Even database connections work
const data = await prisma.user.findMany();
return <div>Full Node.js support!</div>;
}
Let's deploy a real Next.js app with full SSR support on Cloudflare.
# Create new Cloudflare project
npm create cloudflare@latest my-nextjs-app -- \
--framework=next --platform=workers
# Deploy
npm run deploy
Ready to see this in action? Check out the complete working example with full source code, deployment configuration, and step-by-step setup instructions here
If you already have a Next.js app running on Vercel, AWS, or anywhere else, here's how to migrate it to Cloudflare.
First, identify which features your app uses:
# Check your Next.js version
npm list next
# Look for these in your code:
grep -r "export const runtime" . # Edge runtime declarations
grep -r "getServerSideProps" . # SSR pages
grep -r "getStaticProps" . # SSG pages
grep -r "app/api" . # API routes
If your app uses Vercel:
# Use Diverce for automatic migration!
npx diverce migrate
# This tool automatically:
# - Adds OpenNext to your project
# - Updates your configuration
# - Creates a PR with all changes
For manual migration:
# Install the OpenNext adapter
npm install -D @opennextjs/cloudflare wrangler
# Remove any Vercel-specific packages
npm uninstall @vercel/analytics @vercel/og
Remove edge runtime declarations:
// ❌ Remove these from all your files
export const runtime = 'edge';
export const dynamic = 'force-dynamic';
// ✅ OpenNext handles this automatically
// Just delete these lines!
Update your next.config.js:
// next.config.js
const { setupDevPlatform } = require('@cloudflare/next-on-pages/next-dev');
// ❌ Remove this if you have it
if (process.env.NODE_ENV === 'development') {
await setupDevPlatform();
}
// ✅ Add this instead
import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";
initOpenNextCloudflareForDev();
const nextConfig = {
// Your existing config stays the same!
images: {
domains: ['example.com'],
},
// Remove any Vercel-specific settings
// outputFileTracing: false, ❌
};
module.exports = nextConfig;
If you're using Vercel KV:
// ❌ Before (Vercel KV)
import { kv } from '@vercel/kv';
await kv.set('key', 'value');
// ✅ After (Cloudflare KV)
export async function GET(request: Request, env: Env) {
await env.MY_KV.put('key', 'value');
return new Response('Saved!');
}
If you're using Vercel Postgres:
// ❌ Before (Vercel Postgres)
import { sql } from '@vercel/postgres';
const { rows } = await sql`SELECT * FROM users`;
// ✅ After (Any PostgreSQL client works!)
import { Pool } from 'pg';
const pool = new Pool({
connectionString: process.env.DATABASE_URL,
});
const { rows } = await pool.query('SELECT * FROM users');
If you're using Vercel Edge Config:
// ❌ Before (Vercel Edge Config)
import { get } from '@vercel/edge-config';
const value = await get('featureFlag');
// ✅ After (Cloudflare KV or D1)
export async function GET(request: Request, env: Env) {
const value = await env.CONFIG_KV.get('featureFlag');
return Response.json({ value });
}
Create a .dev.vars file for local development:
# .dev.vars (like .env.local but for Cloudflare)
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
NEXTAUTH_SECRET=your-secret-key
NEXT_PUBLIC_API_URL=https://api.example.com
Add bindings to wrangler.toml:
Before that
Optional: create the R2 bucket for the cache If you added R2 incremental cache in your open-next.config.ts.
Run this command to create it:
npx wrangler r2 bucket create your-bucket-name
name = "my-nextjs-app"
main = ".open-next/worker.js"
compatibility_date = "2025-07-27"
compatibility_flags = ["nodejs_compat"]
# Static assets configuration
[assets]
directory = ".open-next/assets"
binding = "ASSETS"
# R2 Buckets
[[r2_buckets]]
binding = "NEXT_INC_CACHE_R2_BUCKET"
bucket_name = "my-bucket-name"
//Run the command below
npm run deploy
*.workers.dev URL or your custom domain, serving from 280+ locations worldwide with automatic SSL.Issue 1: Dynamic imports failing
// ❌ This might fail
const MyComponent = dynamic(() => import('./MyComponent'), {
ssr: false
});
// ✅ Ensure proper configuration
const MyComponent = dynamic(
() => import('./MyComponent'),
{
ssr: false,
loading: () => <div>Loading...</div>
}
);
Issue 2: File system access
// ❌ This won't work in production
import fs from 'fs';
const data = fs.readFileSync('./data.json');
// ✅ Use static imports or fetch
import data from './data.json';
// OR
const response = await fetch('/data.json');
const data = await response.json();
Issue 3: Image optimization
// ✅ Next/Image works but needs configuration
// In next.config.js
module.exports = {
images: {
loader: 'custom',
loaderFile: './image-loader.js',
},
};
// image-loader.js
export default function cloudflareLoader({ src, width, quality }) {
const params = [`width=${width}`];
if (quality) {
params.push(`quality=${quality}`);
}
const paramsString = params.join(',');
return `/cdn-cgi/image/${paramsString}/${src}`;
}
# 1. Build and preview locally
npm run preview
# 2. Check for errors
# Common errors and fixes:
# "Cannot find module 'fs'"
# → Remove file system operations
# "window is not defined"
# → Wrap in useEffect or check typeof window
# "Module not found: Can't resolve 'encoding'"
# → Add to externals in next.config.js
# 3. Test all your routes
curl http://localhost:8787/api/health
curl http://localhost:8787/dashboard
Cloudflare's free tier includes:
100,000 requests per day (resets at midnight UTC)
10ms CPU time per request (plenty for SSR)
128MB memory per Worker
Unlimited static asset requests 🎉
// Let's calculate what 100k requests means:
// Average SSR page: ~50ms total time (including I/O)
// CPU time used: ~5-10ms
// Memory used: ~30-50MB
// Daily capacity on free tier:
// - 100,000 page views
// - ~4,166 page views per hour
// - ~69 page views per minute
// That's enough for:
// - A blog with 50k daily visitors (2 pages each)
// - A SaaS dashboard with 10k daily active users
// - An e-commerce site with 20k daily shoppers
// app/api/process/route.ts
import { createHash } from 'crypto';
import { headers } from 'next/headers';
export async function POST(request: Request) {
const body = await request.json();
// ✅ Node.js crypto works!
const hash = createHash('sha256')
.update(body.data)
.digest('hex');
// ✅ Headers manipulation
const headersList = headers();
const userAgent = headersList.get('user-agent');
// ✅ Complex processing
const result = await processDataWithNodeAPIs(body);
return Response.json({
hash,
processed: result,
userAgent
});
}
// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
export function middleware(request: NextRequest) {
// Runs at the edge for EVERY request
const country = request.geo?.country || 'US';
// Add custom headers
const response = NextResponse.next();
response.headers.set('x-user-country', country);
// Redirect based on geo
if (country === 'CN' && request.nextUrl.pathname === '/') {
return NextResponse.redirect(new URL('/cn', request.url));
}
return response;
}
export const config = {
matcher: '/((?!api|_next/static|_next/image|favicon.ico).*)',
};
// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
// Pre-build these pages
return [
{ slug: 'getting-started' },
{ slug: 'advanced-features' }
];
}
export default async function BlogPost({ params }: { params: { slug: string } }) {
const post = await fetch(`https://api.blog.com/posts/${params.slug}`, {
next: { revalidate: 3600 } // Revalidate every hour
});
return <article>{/* Your content */}</article>;
}
Before deploying to production, ensure:
✅ nodejs_compat flag is set
✅ Environment variables are configured in Cloudflare dashboard
✅ R2 bucket is created for caching (optional)
✅ Custom domain is configured
✅ Preview deployments are working
# Deploy to production
npm run deploy -- --env production
# Deploy preview
npm run deploy -- --env preview
Your app only uses Web APIs
You need the absolute fastest cold starts
You're building a simple marketing site
You need Node.js APIs (crypto, fs, etc.)
You're using Prisma or other Node.js ORMs
You have existing Next.js apps to migrate
You want the full Next.js feature set
With OpenNext adapter reaching v1.0, deploying production Next.js apps on Cloudflare is finally practical. You get:
True SSR with full Node.js support
Global edge deployment from 280+ locations
Generous free tier for getting started
Seamless scaling when you grow
Remember: You're not choosing between features and performance anymore. You can have both.