ANMOLMAAN.DEV
← Blog Index
Backend & Edge•8 min read

Deploy Next.js to Cloudflare Pages in 2025: Complete Guide

By: Anmol Maan•Published: 2025-04-05

Why Cloudflare Pages is Great for Next.js

Next.js is the leading framework for building React-based web applications. When it comes to hosting static websites, portfolios, and blogs, Cloudflare Pages offers a superior alternative to Vercel or Netlify:

  • ■**Unlimited Free Bandwidth**: Vercel limits free accounts to 100GB. Cloudflare has no bandwidth caps on pages.
  • ■**Fastest Global Edge**: Serves pages from Cloudflare's massive global network.
  • ■**Security Toggles**: Access to custom firewall rules, Bot Fight Mode, and AI Labyrinth.

This guide covers deploying static Next.js apps to Cloudflare Pages.

1. Setting Up Static Export in Next.js

To deploy Next.js onto Cloudflare Pages without running Node server instances, you must use static export.

Open your `next.config.ts` or `next.config.js` and configure the output:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "export", // Enables static export
  images: {
    unoptimized: true, // Required for static export
  },
};

export default nextConfig;

When you run `npm run build`, Next.js compiles your code and outputs static HTML/CSS/JS files into the `out/` folder.

2. Managing Custom Headers (`_headers`)

Static exports do not support Next.js's dynamic runtime configurations (like `next.config.js` headers or redirect parameters). Instead, Cloudflare Pages reads custom configurations from a file named `_headers` in the output directory.

To apply headers, create a file named `_headers` in your `public/` folder (it will be copied to `out/` automatically on build):

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

3. Deploying to Cloudflare Dashboard

1. Log in to the [Cloudflare Dashboard](https://dash.cloudflare.com/).

2. Navigate to Workers & Pages > Create application > Pages > Connect to Git.

3. Authorize your GitHub repository.

4. Set the Build settings:

  • ■**Framework Preset**: `Next.js (Static HTML Export)`
  • ■**Build Command**: `npm run build`
  • ■**Build Output Directory**: `out`

5. Save and deploy.

Your site is now live! You can add a custom domain under the Page settings.

CTA: Deploy Your Website

Need help configuring Next.js, custom headers, or Cloudflare DNS? I configured this portfolio on Cloudflare Pages with strict security parameters. Email me at [hello@anmolmaan.dev](mailto:hello@anmolmaan.dev) and let's get your site deployed.

Frequently Asked Questions

Q:Are Next.js dynamic API routes supported on static Cloudflare Pages?

No. Static export compiles pages to HTML/CSS. If you require serverless APIs, you must deploy them separately as Cloudflare Workers or run Next.js in SSR mode using @cloudflare/next-on-pages.

Q:How do you handle redirects on Cloudflare Pages static exports?

Redirects must be specified inside a file named "_redirects" inside the public/ folder, which gets copied to the build root folder (e.g., "/old-path /new-path 301").

Q:Why must Next.js images be unoptimized for static builds?

By default, Next.js optimizes images dynamically on-demand using a server runtime. Because static export has no server, image optimization must be disabled or offloaded to external image optimization APIs.

Q:Does Cloudflare Pages offer free analytics?

Yes, Cloudflare Web Analytics is available for free, privacy-friendly, and lightweight (runs without cookies).

Q:How do you configure custom subdomains on Cloudflare Pages?

You can map custom subdomains in the Pages project dashboard under "Custom Domains". Cloudflare will automatically provision SSL certificates and update your DNS records.