cloudflare pages

Jump to bottom

Jayson Knight edited this page Mar 4, 2026 · 2 revisions

Cloudflare Pages Deployment Guide

This guide explains how to deploy the Adblock Compiler UI to Cloudflare Pages.

Overview

This project uses Cloudflare Workers for the main API/compiler service and Cloudflare Pages for hosting the static UI files in the public/ directory.

Important: Do NOT use `deno deploy`

⚠️ Common Mistake: This project is NOT deployed using deno deploy. While this is a Deno-based project, deployment to Cloudflare uses Wrangler, not Deno Deploy.

Why not Deno Deploy?

This project targets Cloudflare Workers runtime, not Deno Deploy
The worker uses Cloudflare-specific bindings (KV, R2, D1, etc.)
The deployment is managed through Wrangler CLI

Deployment Options

Option 1: Automated Deployment via GitHub Actions (Recommended)

The repository includes automated CI/CD that deploys to Cloudflare Workers and Pages automatically.

See .github/workflows/ci.yml for the deployment configuration.

Requirements:

Set repository secrets:
- CLOUDFLARE_API_TOKEN
- CLOUDFLARE_ACCOUNT_ID
Enable deployment by setting repository variable:
- ENABLE_CLOUDFLARE_DEPLOY=true

Option 2: Manual Deployment

Workers Deployment

# Install dependencies
npm install

# Deploy worker
npm run deploy
# or
wrangler deploy

Pages Deployment

# Deploy public directory to Pages
wrangler pages deploy public --project-name=adblock-compiler-ui

Cloudflare Pages Dashboard Configuration

If you're setting up Cloudflare Pages through the dashboard, use these settings:

Build Configuration

Setting	Value
Framework preset	None
Build command	`npm install`
Build output directory	`public`
Root directory	(leave empty)

Environment Variables

Variable	Value
`NODE_VERSION`	`22`

⚠️ Critical: Deploy Command

DO NOT set a deploy command to deno deploy. This will cause errors because:

Deno is not installed in the Cloudflare Pages build environment by default
This project uses Wrangler for deployment, not Deno Deploy
The static files in public/ don't require any build step

Correct configuration:

Deploy command: Leave empty or use echo "No deploy command needed"

Common Errors

Error: `/bin/sh: 1: deno: not found`

Symptom:

Executing user deploy command: deno deploy
/bin/sh: 1: deno: not found
Failed: error occurred while running deploy command

Solution: Remove or change the deploy command in Cloudflare Pages dashboard settings:

Go to Pages project settings
Navigate to "Builds & deployments"
Under "Build configuration", clear the "Deploy command" field
Save changes

See Troubleshooting for more deployment issue solutions.

Error: Build fails with missing dependencies

Solution: Ensure the build command is set to npm install.

Architecture

flowchart TB
    PAGES["Cloudflare Pages"]
    subgraph STATIC["Static Files (public/)"]
        I["index.html (Admin Dashboard)"]
        C["compiler.html (Compiler UI)"]
        T["test.html (API Tester)"]
    end
    WORKERS["Cloudflare Workers"]
    subgraph WORKER_INNER["Worker (worker/worker.ts)"]
        API["API endpoints"]
        SVC["Compiler service"]
        BINDINGS["KV, R2, D1 bindings"]
    end

    PAGES --> I
    PAGES --> C
    PAGES --> T
    PAGES -->|calls| WORKERS
    WORKERS --> API
    WORKERS --> SVC
    WORKERS --> BINDINGS

Verification

After deployment, verify:

Pages URL: https://YOUR-PROJECT.pages.dev
- Should show the admin dashboard
- Should load without errors
Worker URL: https://adblock-compiler.YOUR-SUBDOMAIN.workers.dev
- API endpoints should respond
- /api should return API documentation
Integration: The Pages UI should successfully call the Worker API

Troubleshooting

Pages deployment works but Worker calls fail

Cause: CORS issues or incorrect Worker URL in UI

Solution:

Check that the Worker URL in the UI matches your deployed Worker
Ensure CORS is configured correctly in worker/worker.ts
Verify the Worker is deployed and accessible

UI shows but API calls return 404

Cause: Worker not deployed or incorrect API endpoint

Solution:

Deploy the Worker: wrangler deploy
Update the API endpoint URL in the UI files if needed
Check Worker logs: wrangler tail

Related Documentation