Deploying Next.js to Cloudflare Pages with Claude Code

Introduction

Cloudflare Pages is a fast, global edge platform for static sites — and it pairs perfectly with Next.js static exports. This tutorial walks through the entire pipeline: installing Wrangler, authenticating with Cloudflare, building a Next.js project, and deploying it with a single command.

The best part? Every step can be done from your terminal through Claude Code, no GUI required.

Prerequisites

• Node.js 18+ and npm
• A Next.js project (or create one: npx create-next-app@latest)
• A Cloudflare account (free tier works)
• Claude Code CLI (npm install -g @anthropic-ai/claude-code)

Step 1: Install Wrangler

Wrangler is Cloudflare's official CLI for managing Pages, Workers, and other Cloudflare resources.

npm install -g wrangler

Verify the installation:

wrangler --version
# → ⛅️ wrangler 4.112.0

Tip: You can also run Wrangler via npx wrangler without a global install — useful for CI pipelines.

Step 2: Authenticate with Cloudflare

Wrangler uses OAuth to authenticate. Run the login command:

npx wrangler login

This opens your browser to Cloudflare's OAuth consent screen. Log in with your Cloudflare account and approve the permissions (pages:write, workers:write, etc.).

Verify the authentication succeeded:

npx wrangler whoami

You should see your account name, account ID, and a list of granted OAuth scopes — crucially including pages (write).

CI/CD Note: For automated deployments (GitHub Actions, GitLab CI), use a Cloudflare API token instead:

codeCOPY

npx wrangler login --browserless
# Then follow the printed URL manually

Or set CLOUDFLARE_PAGES_TOKEN as a repository secret.

Step 3: Configure Next.js for Static Export

Cloudflare Pages works best with static exports. Update your next.config.js (or next.config.mjs):

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true, // Required for static export
  },
};

export default nextConfig;

Key points:

• output: 'export' generates a static out/ directory
• images.unoptimized: true disables the Next.js image optimization API (not available in static mode)
• If you use getStaticProps with revalidate, static export won't support ISR — prebuild everything at deploy time

Step 4: Build the Project

Build the static export:

cd frontend
npm install
npm run build

This produces an out/ directory containing your fully static site — HTML, CSS, JS, and assets.

Step 5: Deploy to Cloudflare Pages

Deploy the out/ directory:

npx wrangler pages deploy out --project-name my-project

Wrangler creates the project on Cloudflare Pages (if it doesn't exist) and deploys the contents. The output shows your deployment URL:

✨ Success! Your project "my-project" is deployed at:
  https://my-project.pages.dev

For subsequent deploys, Wrangler reuses the same project:

npm run build && npx wrangler pages deploy out --project-name my-project

Custom Domain

To add a custom domain:

npx wrangler pages project list           # List projects
npx wrangler pages deployment list --project-name my-project  # List deployments

Then in the Cloudflare Dashboard → Pages → your project → Custom domains, add your domain. Cloudflare automatically provisions an SSL certificate.

Step 6: Deploy with Claude Code

Claude Code can orchestrate the full pipeline in one go. In your project directory:

claude -p "Build the Next.js site and deploy to Cloudflare Pages"

Claude runs npm run build, then npx wrangler pages deploy out --project-name my-project. For multi-repo pipelines, Claude can clone, install, build, and deploy in sequence:

claude -p "Clone my-nextjs-project, install deps, build, and deploy to Cloudflare Pages as 'my-project'"

Step 7: Automate with GitHub Actions

For automated deployments on every push, add .github/workflows/deploy.yml:

name: Deploy to Cloudflare Pages
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci && npm run build
      - run: npx wrangler pages deploy out --project-name my-project
        env:
          CLOUDFLARE_PAGES_TOKEN: ${{ secrets.CLOUDFLARE_PAGES_TOKEN }}

Set CLOUDFLARE_PAGES_TOKEN in your GitHub repo secrets (generate it in Cloudflare Dashboard → API Tokens → Create Token → Cloudflare Pages template).

Troubleshooting

"Missing output directory 'out/'"

Your Next.js project doesn't have output: 'export' in next.config.js. Add it and rebuild.

"Authentication required"

Run npx wrangler login again — OAuth tokens expire periodically. In CI, verify your CLOUDFLARE_PAGES_TOKEN is set correctly.

"Build failed: unknown error"

Check Node.js version — Cloudflare Pages requires Node 18+. Also verify your Next.js version is compatible with static export (App Router projects need Next.js 13.4+).

"Custom domain not working"

DNS propagation takes a few minutes. In the Cloudflare Dashboard, check that your domain's nameservers point to Cloudflare and the SSL/TLS setting is "Full" (not "Flexible").

Summary

npm install -g wrangler          # Install
npx wrangler login               # Auth
npx wrangler whoami              # Verify
npm run build && npx wrangler pages deploy out --project-name my-project  # Deploy

Four commands, one static site, globally distributed via Cloudflare's edge network. And with Claude Code, even those four commands reduce to a single prompt.