Deploy to Cloudflare Pages

Publish your Opal Editor sites to Cloudflare’s global network with Pages for fast, secure hosting

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

Related Resources

• Cloudflare Pages Documentation
• Cloudflare API Docs
• Publishing Overview
• Build System