Cloudflare Pages Deployment

Overview

Cloudflare Pages provides a fast, secure platform for deploying static sites and full-stack applications. For Fumadocs, you have two deployment options:

Static Export - Build and deploy as static HTML/CSS/JS files
Full-Stack with OpenNext - Deploy Next.js with server-side features

Static Export (Recommended)

The simplest approach for most documentation sites.

Configure Static Export

Enable static export in your Next.js configuration:

import { createMDX } from 'fumadocs-mdx/next';

const withMDX = createMDX();

/** @type {import('next').NextConfig} */
const config = {
  output: 'export',
  reactStrictMode: true,
  images: {
    unoptimized: true,
  },
};

export default withMDX(config);

See Static Export for complete configuration details.

Configure Search

Set up client-side search for static sites:

import { SearchDialog } from 'fumadocs-ui/components/dialog/search';

export function Search() {
  return (
    <SearchDialog
      search={{
        type: 'static',
        index: '/static.json',
      }}
    />
  );
}

Build Your Site

npm run build

Static files are output to the out/ directory.

Deploy to Cloudflare Pages

Option 1: Wrangler CLI

# Install Wrangler
npm install -g wrangler

# Deploy
wrangler pages deploy out/

Option 2: Direct Upload

Go to Cloudflare Dashboard

Navigate to Workers & Pages → Create

Select “Upload assets”

Upload the out/ directory

Option 3: Git Integration

Connect your repository for automatic deployments:

Workers & Pages → Create → Connect to Git

Select your repository

Configure build settings:

Build command: npm run build
Build output directory: out

Deploy

Full-Stack with OpenNext

For Next.js applications requiring server-side features (API routes, SSR, ISR).

Fumadocs does not work on Cloudflare’s Edge runtime. Use OpenNext for Cloudflare to deploy with server-side features.

Install OpenNext

npm install --save-dev @opennextjs/cloudflare

Configure OpenNext

Create an OpenNext configuration:

module.exports = {
  platform: 'cloudflare',
  cloudflare: {
    routes: [
      {
        pattern: '/api/*',
        custom_handler: true,
      },
    ],
  },
};

Update Build Script

{
  "scripts": {
    "build": "next build && opennext build",
    "deploy": "wrangler pages deploy .open-next/worker"
  }
}

Build and Deploy

npm run build
npm run deploy

Configuration

wrangler.toml

Configure Cloudflare Workers/Pages settings:

wrangler.toml

name = "fumadocs"
pages_build_output_dir = "out"
compatibility_date = "2024-01-01"
compatibility_flags = ["nodejs_compat"]

[env.production]
route = "https://docs.example.com/*"

[env.production.vars]
NODE_ENV = "production"

Environment Variables

Set environment variables in Cloudflare Dashboard:

Workers & Pages → Your Project → Settings
Environment Variables → Add Variable
Add for Production and Preview environments

For local development:

.dev.vars

NEXT_PUBLIC_SITE_URL=http://localhost:3000
API_KEY=your-secret-key

.dev.vars is gitignored by default. Use it for local secrets.

Custom Domain

Add a custom domain:

Add Domain

Workers & Pages → Your Project → Custom Domains

Click “Set up a custom domain”

Enter your domain (e.g., docs.example.com)

Configure DNS

If your domain is on Cloudflare:

DNS records are automatically configured

If using external DNS:

CNAME docs your-project.pages.dev

SSL/TLS

SSL certificates are automatically provisioned.

Build Configuration

Build Settings

Configure in Cloudflare Dashboard or wrangler.toml:

wrangler.toml

[build]
command = "npm run build"
cwd = "."
watch_dirs = ["content", "app", "components"]

[build.upload]
format = "directory"
dir = "out"

Node.js Version

Specify Node.js version:

.nvmrc

Or set in dashboard: Settings → Build & Deployments → Node Version

Image Optimization

Cloudflare Images integration:

Option 1: Unoptimized Images

For static exports:

next.config.mjs

const config = {
  output: 'export',
  images: {
    unoptimized: true,
  },
};

Option 2: Cloudflare Images

Use Cloudflare’s image optimization:

next.config.mjs

const config = {
  images: {
    loader: 'custom',
    loaderFile: './cloudflare-image-loader.js',
  },
};

cloudflare-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}`;
}

Option 3: Cloudflare Images Service

For remote images:

next.config.mjs

const config = {
  images: {
    domains: ['imagedelivery.net'],
  },
};

Search Integration

Static Search (Orama)

For static exports, use client-side search:

app/static.json/route.ts

import { allDocs } from '@/.source';
import { createSearchAPI } from 'fumadocs-core/search/server';

const api = createSearchAPI('advanced', {
  indexes: allDocs.map((page) => ({
    id: page.url,
    title: page.data.title,
    description: page.data.description,
    url: page.url,
    structuredData: page.data.structuredData,
  })),
});

export const GET = api.staticGET();
export const dynamic = 'force-static';

Algolia Search

Algolia works seamlessly with Cloudflare Pages:

components/search.tsx

import { SearchDialog } from 'fumadocs-ui/components/dialog/search';
import algoliasearch from 'algoliasearch/lite';

const searchClient = algoliasearch(
  process.env.NEXT_PUBLIC_ALGOLIA_APP_ID!,
  process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_KEY!
);

export function Search() {
  return (
    <SearchDialog
      search={{
        type: 'algolia',
        client: searchClient,
        index: 'docs',
      }}
    />
  );
}

Redirects and Headers

Redirects

wrangler.toml

[[redirects]]
from = "/old-page"
to = "/new-page"
status = 301

[[redirects]]
from = "/docs/*"
to = "/documentation/:splat"
status = 302

Or use _redirects file:

public/_redirects

/old-page /new-page 301
/docs/* /documentation/:splat 302

# SPA fallback
/* /index.html 200

Headers

Custom headers configuration:

wrangler.toml

[[headers]]
for = "/*"
[headers.values]
"X-Frame-Options" = "DENY"
"X-Content-Type-Options" = "nosniff"
"Referrer-Policy" = "strict-origin-when-cross-origin"

[[headers]]
for = "/static/*"
[headers.values]
"Cache-Control" = "public, max-age=31536000, immutable"

Or use _headers file:

public/_headers

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff

/static/*
  Cache-Control: public, max-age=31536000, immutable

Performance Optimization

Caching Strategy

Cloudflare automatically caches static assets. Configure cache TTL:

wrangler.toml

[site]
bucket = "./out"

[[rules]]
action = "cache"
pattern = "*.js"
cache_ttl = 31536000

[[rules]]
action = "cache"
pattern = "*.css"
cache_ttl = 31536000

Minification

Enable automatic minification:

Cloudflare Dashboard → Speed → Optimization
Enable:
- Auto Minify (HTML, CSS, JS)
- Brotli compression

HTTP/3 and QUIC

Enable for faster connections:

Cloudflare Dashboard → Network
Enable HTTP/3 (with QUIC)

Preview Deployments

Cloudflare automatically creates preview deployments:

Production: Deploys from your default branch
Preview: Deploys from pull requests and branches

Access previews at:

https://[branch].[project].pages.dev

CI/CD Integration

GitHub Actions

.github/workflows/deploy.yml

name: Deploy to Cloudflare Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      
      - run: npm ci
      - run: npm run build
      
      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: fumadocs
          directory: out
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}

GitLab CI

.gitlab-ci.yml

pages:
  stage: deploy
  image: node:20
  script:
    - npm ci
    - npm run build
    - npx wrangler pages deploy out/
  only:
    - main
  variables:
    CLOUDFLARE_API_TOKEN: $CLOUDFLARE_API_TOKEN
    CLOUDFLARE_ACCOUNT_ID: $CLOUDFLARE_ACCOUNT_ID

Troubleshooting

Build Failures

Issue: Build times out or fails Solution:

Check build logs in Cloudflare Dashboard
Verify Node.js version compatibility
Ensure all dependencies are in package.json
Check memory limits (increase if needed)

404 Errors

Issue: Pages return 404 after refresh Solution: Add SPA fallback to _redirects:

/* /index.html 200

Function Size Limits

Issue: “Worker exceeds size limit” Solution:

Use static export instead of OpenNext
Reduce bundle size:
```
npm run build -- --analyze
```
Split large pages or features

Environment Variables Not Working

Issue: Environment variables undefined Solution:

Verify variables are set in Cloudflare Dashboard
Use NEXT_PUBLIC_ prefix for client-side variables
Rebuild and redeploy after adding variables
For local development, use .dev.vars

Monitoring

Analytics

Enable Web Analytics:

Cloudflare Dashboard → Analytics → Web Analytics
Add site
Install beacon (automatic for Pages)

Real User Monitoring

View performance metrics:

Page load times
Core Web Vitals
Geographic distribution

Security

Access Policies

Restrict access to preview deployments:

Workers & Pages → Your Project → Settings
Access Policies → Add policy
Configure authentication (email, GitHub, etc.)

Security Headers

Add recommended security headers:

public/_headers

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  X-XSS-Protection: 1; mode=block
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: camera=(), microphone=(), geolocation=()

Getting Started

Core Concepts

Framework Integration

Content Sources

UI Components

Markdown & MDX

Features

Integrations

Deployment

​Overview

​Static Export (Recommended)

​Full-Stack with OpenNext

​Configuration

​wrangler.toml

​Environment Variables

​Custom Domain

​Build Configuration

​Build Settings

​Node.js Version

​Image Optimization

​Option 1: Unoptimized Images

​Option 2: Cloudflare Images

​Option 3: Cloudflare Images Service

​Search Integration

​Static Search (Orama)

​Algolia Search

​Redirects and Headers

​Redirects

​Headers

​Performance Optimization

​Caching Strategy

​Minification

​HTTP/3 and QUIC

​Preview Deployments

​CI/CD Integration

​GitHub Actions

​GitLab CI

​Troubleshooting

​Build Failures

​404 Errors

​Function Size Limits

​Environment Variables Not Working

​Monitoring

​Analytics

​Real User Monitoring

​Security

​Access Policies

​Security Headers

​Next Steps

Build docs developers (and LLMs) love

Overview

Static Export (Recommended)

Full-Stack with OpenNext

Configuration

wrangler.toml

Environment Variables

Custom Domain

Build Configuration

Build Settings

Node.js Version

Image Optimization

Option 1: Unoptimized Images

Option 2: Cloudflare Images

Option 3: Cloudflare Images Service

Search Integration

Static Search (Orama)

Algolia Search

Redirects and Headers

Redirects

Headers

Performance Optimization

Caching Strategy

Minification

HTTP/3 and QUIC

Preview Deployments

CI/CD Integration

GitHub Actions

GitLab CI

Troubleshooting

Build Failures

404 Errors

Function Size Limits

Environment Variables Not Working

Monitoring

Analytics

Real User Monitoring

Security

Access Policies

Security Headers

Next Steps