Skip to main content
Cloudflare Pages provides fast, secure, and free hosting on Cloudflare’s global network. Opal Editor integrates with Cloudflare’s API to deploy your static sites directly to Pages.

​
Prerequisites

Before deploying to Cloudflare Pages:
  • A Cloudflare account (sign up at cloudflare.com)
  • A Cloudflare API token with Pages permissions
  • A completed build ready for deployment

​
Authentication Setup

Cloudflare Pages requires an API token for authentication.
1

Create an API token

  1. Go to Cloudflare Dashboard > My Profile > API Tokens
  2. Click “Create Token”
  3. Use the “Edit Cloudflare Workers” template or create a custom token
  4. Ensure it has these permissions:
    • Account > Cloudflare Pages > Edit
  5. Copy the generated token
2

Add to Opal Editor

Create a new Cloudflare API authentication in Opal Editor and paste your token.
Keep your API token secure. It provides access to your Cloudflare account and can modify your Pages projects.

​
Destination Configuration

Configure your Cloudflare Pages deployment destination: 
{
  "remoteAuthId": "your-auth-id",
  "label": "My Cloudflare Pages Site",
  "meta": {
    "accountName": "My Account",
    "accountId": "auto-resolved",
    "projectName": "my-project"
  }
}

​
Configuration Fields

  • accountName (required): Your Cloudflare account name
    • Displayed in the Cloudflare dashboard
    • Used to auto-resolve account ID
  • accountId (auto-resolved): Automatically resolved from account name
  • projectName (required): Your Pages project name
    • Must be unique within your account
    • Used in the default URL
The account ID is automatically resolved from your account name during validation.

​
Deployment Process

1

Select account and project

Configure your deployment:
  • Choose your Cloudflare account by name
  • Specify a project name
  • Project will be created if it doesn’t exist
2

Build your site

Complete a build in Opal Editor:
  • Source files are processed
  • Static HTML is generated
  • Assets are prepared
  • Files are ready for upload
3

Deploy to Cloudflare Pages

Start deployment:
  • Files are uploaded to Cloudflare Pages
  • Project is created if needed
  • Deployment is processed on Cloudflare’s network
  • Progress is tracked in real-time
4

Access your site

Your site is live at:
  • Main URL: https://{projectName}.pages.dev
  • Deployment URL: Specific URL for this deployment

​
How It Works

The Cloudflare deployment agent (RemoteAuthCloudflareAPIAgent) handles:
  1. Account Resolution: Validates account name and resolves account ID
  2. Project Management: Creates project if it doesn’t exist
  3. File Upload: Converts and uploads files to Cloudflare Pages
  4. Deployment Tracking: Monitors deployment status
  5. URL Generation: Returns both main and deployment-specific URLs

​
File Preparation

Opal Editor prepares files for Cloudflare Pages: 
// Files converted to deployment format:
[
  {
    type: "file",
    path: "index.html",
    encoding: "utf-8",
    getContent: async () => content
  }
]
  • Text files (HTML, CSS, JS): UTF-8 encoding
  • Binary files (images, fonts): Base64 encoding
  • All file types supported

​
Features

​
Global CDN

Cloudflare’s massive global network:
  • 300+ data centers worldwide
  • Content served from nearest location
  • Automatic edge caching
  • DDoS protection included

​
Unlimited Bandwidth

Cloudflare Pages includes:
  • Unlimited bandwidth on all plans
  • No usage limits
  • Free for static sites

​
Automatic HTTPS

Security by default:
  • Automatic SSL certificates
  • HTTPS enforced
  • Modern TLS versions
  • No configuration needed

​
Web Analytics

Free analytics included:
  • Page views and visits
  • Geographic distribution
  • Referrer tracking
  • No impact on performance

​
Account Management

Cloudflare supports multiple accounts:
  • Personal accounts
  • Organization accounts
  • Multiple projects per account
The agent automatically:
  • Fetches all accessible accounts
  • Resolves account ID from name
  • Lists projects within selected account

​
Troubleshooting

​
Account Not Found

If “Account name not found”:
  • Verify the account name matches exactly
  • Check your API token has access to the account
  • Ensure you’re using the correct account name from the dashboard
Solution: Copy the exact account name from your Cloudflare Dashboard.

​
Permission Errors

If you see permission errors:
  1. Verify API token has Cloudflare Pages Edit permissions
  2. Check token hasn’t expired
  3. Ensure token is scoped to the correct account
  4. Try creating a new token with appropriate permissions

​
Deployment Failures

If deployment fails:
  • Check deployment logs for specific errors
  • Verify your build completed successfully
  • Ensure all files are valid
  • Check Cloudflare’s status page for outages

​
Project Creation Issues

If project creation fails:
  • Verify project name is unique in your account
  • Check name follows Cloudflare’s naming rules
  • Ensure you have available project slots
  • Try a different project name

​
Best Practices

  1. Use descriptive project names: Choose meaningful names for easy identification
  2. Monitor deployments: Watch logs for warnings or errors
  3. Test before deploying: Ensure builds complete successfully locally
  4. Configure custom domains: Set up custom domains in Cloudflare dashboard
  5. Enable analytics: Use Cloudflare’s free Web Analytics for insights
  6. Set up redirects: Configure redirects and headers for optimal performance

​
Advanced Configuration

​
Custom Domains

Add custom domains in the Cloudflare dashboard:
  1. Navigate to your Pages project
  2. Go to Custom domains tab
  3. Add your domain
  4. Cloudflare handles DNS automatically if domain is on Cloudflare

​
Headers and Redirects

Configure custom headers and redirects: Create a _headers file: 
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
Create a _redirects file: 
/old-path  /new-path  301
/blog/*    /articles/:splat  302

​
Build Configuration

Include a wrangler.toml for advanced configuration: 
name = "my-project"

[site]
bucket = "."

[[redirects]]
from = "/*"
to = "/index.html"
status = 200

​
Edge Functions

While Opal Editor deploys static files, you can add edge functions:
  • Create functions directory in your build
  • Add JavaScript/TypeScript files
  • Deploy alongside static content
  • Functions run on Cloudflare’s edge network

​
Performance Optimization

​
Caching

Cloudflare automatically caches:
  • Static assets (images, CSS, JS)
  • HTML with appropriate cache headers
  • Configurable cache rules

​
Compression

Automatic compression:
  • Brotli compression for modern browsers
  • Gzip fallback for older browsers
  • No configuration required

​
HTTP/3

Modern protocol support:
  • HTTP/3 enabled by default
  • QUIC protocol for faster connections
  • Automatic fallback to HTTP/2

Build docs developers (and LLMs) love

Get started for freeTalk to us