Cloudflare Pages Deployment Guide: Complete Tutorial 2026

Introduction

Cloudflare Pages is a JAMstack platform that makes deploying static sites and serverless functions incredibly easy. With global CDN, automatic HTTPS, and Git integration, it's an excellent choice for Next.js, React, and other modern web frameworks.

What is Cloudflare Pages?

Cloudflare Pages is a platform for deploying static websites and serverless functions:

• Global CDN: Content delivered from 300+ locations worldwide
• Automatic HTTPS: Free SSL certificates for all sites
• Git Integration: Deploy directly from GitHub, GitLab, Bitbucket
• Preview Deployments: Test changes before production
• Serverless Functions: Run server-side code at the edge
• Unlimited Bandwidth: Free tier includes unlimited requests

Why Choose Cloudflare Pages?

Advantages

• Free Tier: Generous free plan for most sites
• Fast Performance: Global edge network
• Easy Setup: Simple deployment process
• Automatic Scaling: Handles traffic spikes
• Preview Deployments: Test before going live
• Custom Domains: Easy domain configuration
• Environment Variables: Secure configuration
• Build Logs: Detailed deployment information

Use Cases

• Static websites
• Next.js applications
• React applications
• Vue.js applications
• JAMstack sites
• Documentation sites
• Portfolio websites
• Marketing sites

Getting Started

Prerequisites

• GitHub/GitLab/Bitbucket account
• Cloudflare account (free)
• Project repository
• Node.js project (for JavaScript frameworks)

Step 1: Create Cloudflare Account

1. Visit cloudflare.com
2. Sign up for free account
3. Verify email address
4. Complete account setup

Step 2: Connect Repository

1. Go to Cloudflare Dashboard
2. Navigate to "Pages"
3. Click "Create a project"
4. Connect your Git provider
5. Authorize Cloudflare access
6. Select your repository

Deploying Next.js

Basic Setup

Build Settings:

• Framework preset: Next.js
• Build command: npm run build or next build
• Build output directory: .next
• Root directory: / (or your project root)

Using @cloudflare/next-on-pages

For full Next.js compatibility:

npm install -D @cloudflare/next-on-pages

Update package.json:

{
  "scripts": {
    "build": "next build && npx @cloudflare/next-on-pages"
  }
}

Build output: .vercel/output/static

Environment Variables

1. Go to project settings
2. Navigate to "Environment Variables"
3. Add variables for:
   • Production
   • Preview
   • Development

Common Variables:

• NODE_ENV=production
• NEXT_PUBLIC_API_URL=...
• Database URLs
• API keys
• Feature flags

Deploying React Apps

Create React App

Build Settings:

• Framework preset: Create React App
• Build command: npm run build
• Build output directory: build
• Root directory: /

Vite React

Build Settings:

• Framework preset: Vite
• Build command: npm run build
• Build output directory: dist
• Root directory: /

Configuration

wrangler.toml (Optional)

For advanced configuration:

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

[env.production]
routes = [
  { pattern = "example.com/*", zone_name = "example.com" }
]

Custom Build Commands

You can customize build process:

• Install dependencies: npm ci
• Run tests: npm test
• Build: npm run build
• Post-build scripts

Environment Variables

Setting Variables

1. Dashboard: Project Settings > Environment Variables
2. wrangler.toml: For local development
3. Secrets: For sensitive data

Variable Types

• Plain Text: Regular configuration
• Secrets: Encrypted, hidden values
• Environment-Specific: Different values per environment

Custom Domains

Adding Domain

1. Go to project settings
2. Navigate to "Custom domains"
3. Click "Set up a custom domain"
4. Enter your domain
5. Add DNS records (CNAME)
6. Wait for SSL provisioning

DNS Configuration

CNAME Record:

• Name: @ or www
• Target: your-project.pages.dev
• Proxy: Enabled (orange cloud)

SSL/TLS:

• Automatic SSL certificates
• Full encryption
• Automatic renewal

Preview Deployments

How It Works

• Every pull request gets preview URL
• Test changes before merging
• Share previews with team
• Automatic cleanup after merge

Preview URLs

Format: https://<branch-name>.<project>.pages.dev

Example: https://feature-new-design.my-site.pages.dev

Serverless Functions

Creating Functions

Create functions/ directory in project root:

functions/
  api/
    hello.js

Example Function:

export async function onRequest(request) {
  return new Response(JSON.stringify({ message: "Hello" }), {
    headers: { "Content-Type": "application/json" }
  });
}

Function Routes

• /api/hello → functions/api/hello.js
• /api/users/[id] → functions/api/users/[id].js
• Dynamic routing supported

Performance Optimization

Automatic Optimizations

• Image Optimization: Automatic image resizing
• Minification: CSS/JS minification
• Compression: Gzip/Brotli compression
• Caching: Intelligent caching strategies
• HTTP/3: Latest protocol support

Best Practices

• Optimize images before upload
• Use modern image formats (WebP, AVIF)
• Minimize JavaScript bundles
• Enable compression
• Use CDN for assets
• Implement lazy loading

Monitoring & Analytics

Build Logs

• View build output
• Debug build failures
• Monitor build times
• Track deployment history

Analytics

• Page views
• Unique visitors
• Top pages
• Referrers
• Countries
• Browsers/devices

Troubleshooting

Common Issues

Build Failures:

• Check build logs
• Verify Node.js version
• Check environment variables
• Review dependencies

Deployment Errors:

• Verify build output directory
• Check file permissions
• Review build command
• Test locally first

Domain Issues:

• Verify DNS records
• Check SSL status
• Wait for propagation
• Contact support if needed

Best Practices

Development Workflow

1. Local Testing: Test builds locally first
2. Preview Deployments: Use previews for testing
3. Environment Variables: Use different values per environment
4. Version Control: Keep config in repository
5. Documentation: Document deployment process

Security

• Use environment variables for secrets
• Enable HTTPS only
• Review access permissions
• Regular security updates
• Monitor for vulnerabilities

Performance

• Optimize images
• Minimize JavaScript
• Use CDN effectively
• Implement caching
• Monitor Core Web Vitals

Comparison with Alternatives

vs Vercel

Cloudflare Pages:

• Unlimited bandwidth (free)
• Global edge network
• Lower cost at scale
• More control

Vercel:

• Better Next.js integration
• More developer tools
• Easier setup
• Better documentation

vs Netlify

Cloudflare Pages:

• Faster global CDN
• Better free tier
• More edge locations
• Lower costs

Netlify:

• More features
• Better CI/CD
• More integrations
• Better documentation

Conclusion

Cloudflare Pages offers an excellent platform for deploying modern web applications. With its generous free tier, global CDN, and easy Git integration, it's perfect for static sites, Next.js apps, and JAMstack projects. Follow this guide to deploy your site and enjoy fast, reliable hosting with automatic scaling.

Don't Want to Manage Deployments?

Moydus handles all hosting, deployment, and infrastructure for every client website — built on the same edge-first stack described in this guide. You focus on your business; we handle the technical layer.

See Moydus web design packages → | View pricing →

Related Reading

• Next.js vs React 2026: Which Framework Should You Choose?
• Web Development Trends 2026
• How to Choose a Web Design Agency