Deploy Next.js to Cloudflare Pages Without the Headaches

The Exact Settings

Build command: npx next build

Output directory: .next

Node.js version: 20 (set in Environment Variables as NODE_VERSION = 20)

Environment Variables

Set them in Cloudflare Pages dashboard under Settings → Environment Variables → Production. Add all NEXT_PUBLIC_ variables there too — they are not public just because they say public in the name, they still need to be set server-side in the build process.

Common Error 1: Functions directory conflict

If you have a /functions folder from a previous Hugo or static site, delete it. Cloudflare Pages interprets that as Cloudflare Workers functions and it conflicts with Next.js API routes.

Common Error 2: Missing NODE_VERSION

Without setting Node version explicitly, Cloudflare defaults to Node 16. Next.js 14 requires Node 18+. Add NODE_VERSION = 20 to your environment variables.

Common Error 3: Edge Runtime compatibility

Some npm packages don't work in the Cloudflare Edge runtime. If you get build errors about Node.js built-ins, add this to next.config.js:

module.exports = {
  output: 'standalone',
  experimental: {
    serverComponentsExternalPackages: ['groq-sdk', '@supabase/supabase-js']
  }
}