EnglishDeploymentDeploy to Cloudflare

Deploy to Cloudflare Pages

Deploying a Nextra 3 site to Cloudflare Pages is powerful but requires specific settings, especially when developing on macOS (Apple Silicon). This guide covers the complete setup and how to avoid cross-platform errors.

1. Project Configuration

Static Export

Open next.config.js and ensure you have enabled static export. This is the most efficient way to host documentation.

next.config.js
const withNextra = require('nextra').default({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.tsx',
})
 
module.exports = withNextra({
  output: 'export', // Required for Static Site Generation
  images: {
    unoptimized: true, // Required for static export
  },
})

⚠️ Cross-Platform Warning (macOS vs Linux)

Nextra relies on native binaries (like @napi-rs/simple-git).

  • Local (macOS): Uses darwin-arm64 binary.
  • Cloudflare (Linux): Needs linux-x64 binary.

If you mistakenly commit package-lock.json generated on macOS, Cloudflare’s build may fail with EBADPLATFORM because it tries to install the Mac binary on Linux.

Recommendation: To avoid this, use npm install instead of npm ci in your build command, or do not commit package-lock.json. The instructions below use the npm install method which is safest.

2. Push to GitHub

Ensure your code is pushed to your remote repository.

git add .
git commit -m "Ready for deployment"
git push origin main

3. Cloudflare Pages Setup (Detailed)

  1. Log in to the Cloudflare Dashboard.
  2. Go to Workers & Pages > Create Application > Pages tab > Connect to Git.
  3. Select your repository (e.g., the-whole-scraps).

Build Settings Configuration

On the “Set up builds and deployments” screen, configure as follows:

  • Project Name: my-nextra3 (or your preference)
  • Production Branch: main
  • Framework Preset: Select Next.js (Static HTML Export).
  • Build Output Directory: out (Automatically set by preset)

⚠️ Critical Settings

  1. Build Command: Change from npx next build to:

    npm install && npm run build

    Why? The standard npm ci (used by default) is strict about lockfiles. Using npm install ensures Cloudflare resolves the correct Linux binaries freshly, ignoring any macOS-specific locks in your repository.

  2. Root Directory:

    • Expand the Build configurations section.
    • If your Nextra app is in a specific folder (e.g., cloudflarepages-nextra/my-nextra3), you MUST enter that path here.
    • Example: cloudflarepages-nextra/my-nextra3

  3. Environment Variables (Optional):

    • Add NODE_VERSION: 18 (or 20) if you want to be explicit, though Cloudflare usually picks a recent version.

4. Deploy

Click Save and Deploy.

Cloudflare will:

  1. Clone your repository.
  2. Enter the Root Directory you specified.
  3. Run npm install (resolving Linux dependencies).
  4. Run npm run build (generating the out folder).
  5. Deploy the out folder to the edge.

5. Automatic Deployments

Once set up, every time you run git push origin main, Cloudflare will detect the change and automatically trigger a new deployment. You can verify this setting in Settings > Builds & deployments.

OverviewCustom Domains