Cloudflare Pages

Cloudflare Pages provides static hosting on their global edge network with generous free tier limits. Excellent performance worldwide with unlimited bandwidth.

Project Setup

1. Go to dash.cloudflare.com and sign up
2. Navigate to Workers & Pages
3. Click Create application > Pages
4. Connect your Git repository

Build Configuration

In the Cloudflare Pages dashboard:

Or create a wrangler.toml file:

name = "my-docs"
compatibility_date = "2024-01-01"

[site]
bucket = ".output/public"

Environment Variables

Set in Settings > Environment variables:

NODE_VERSION = 20
NUXT_APP_BASE_URL = /
NUXT_PUBLIC_SITE_URL = https://docs.example.com

Custom Domain

1. Go to Custom domains
2. Add your domain
3. If domain is on Cloudflare:
   • DNS is configured automatically
4. If domain is elsewhere:
   • Add CNAME record pointing to *.pages.dev

SSL is automatically provisioned.

Deployment

Automatic Deploys

Pushes to your connected branch trigger automatic builds.

Manual Deploy via CLI

# Install Wrangler
npm install -g wrangler

# Login
wrangler login

# Deploy
npm run generate
wrangler pages deploy .output/public

Direct Upload

1. Run npm run generate locally
2. Go to Cloudflare Pages dashboard
3. Click Create deployment
4. Upload the .output/public folder

Advanced Configuration

Headers

Create public/_headers:

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

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

Redirects

Create public/_redirects:

/old-page /new-page 301
/blog/* /posts/:splat 301

Functions

Add serverless functions in functions/:

// functions/api/hello.ts
export async function onRequest(context) {
  return new Response('Hello!')
}

Free Tier Limits

Cloudflare Pages is generous:

Troubleshooting

Build Failures

Check build logs in Deployments. Common issues:

• Node version not set (add NODE_VERSION environment variable)
• Wrong build output directory (must be .output/public)
• Missing dependencies

Slow Builds

Cloudflare Pages doesn't cache node_modules between builds. Each build installs fresh. This is slower but more reliable.

404 on Subpages

Ensure all routes are pre-rendered. Cloudflare Pages serves static files only—no server-side rendering.

Check your build output has the expected HTML files:

ls -la .output/public/guide/