Cloudflare

Deploy to Cloudflare Workers using the OpenNext Cloudflare adapter.

Prerequisites

Cloudflare account
Bun installed locally or in CI
Required Cloudflare credentials configured in CI when deploying from GitHub:
- CLOUDFLARE_API_TOKEN - API token with Workers deploy permissions
- CLOUDFLARE_ACCOUNT_ID - Your Cloudflare account ID

Architecture

The application uses @opennextjs/cloudflare to adapt Next.js for Cloudflare Workers:

Build Process: bun run cf:build generates the OpenNext output
Entry Point: .open-next/worker.js (Cloudflare Worker)
Static Assets: .open-next/assets/ (served via Cloudflare CDN)
Configuration: wrangler.toml and open-next.config.ts

Local Development

# Install dependencies
bun install

# Run development server
bun run dev

# Build for Cloudflare
bun run cf:build

# Preview locally with Cloudflare environment
bun run cf:preview

Deployment Methods

1. Automated Deployment (Recommended)

GitHub Actions can deploy from the repository once Cloudflare credentials and ClickHouse secrets are configured.

See: .github/workflows/cloudflare.yml

2. Manual Deployment via CLI

# Set Worker secrets from .env.local
bun run cf:config

# Deploy to Cloudflare
bun run cf:deploy

3. Cloudflare Dashboard or CI

If configuring a build command in Cloudflare or another CI runner:

bun install --frozen-lockfile
bun run cf:build

Use Node.js 22.22.1 or newer when a Node runtime is required by the runner.

Configuration

wrangler.toml

Main Cloudflare Workers configuration:

Entry point: .open-next/worker.js
Assets directory: .open-next/assets
Node.js compatibility enabled
R2, D1, KV, and Durable Objects bindings configured

open-next.config.ts

OpenNext Cloudflare adapter configuration:

Incremental cache: KV namespace
Tag cache: D1 database
Queue: Durable Objects
Cache interception enabled

Environment Variables

Configure these as Worker secrets or environment variables:

CLICKHOUSE_HOST - ClickHouse server URL(s), comma-separated for multi-host
CLICKHOUSE_USER - Authentication username(s), comma-separated for multi-host
CLICKHOUSE_PASSWORD - Authentication password(s), comma-separated for multi-host
CLICKHOUSE_NAME - Optional instance name(s), comma-separated for multi-host
CLICKHOUSE_MAX_EXECUTION_TIME - Query timeout in seconds

Bindings

The application requires these Cloudflare resources:

KV Namespace

Binding: NEXT_INC_CACHE_KV
Purpose: Incremental static regeneration cache

D1 Database

Binding: NEXT_TAG_CACHE_D1
Database: clickhouse-monitor
Purpose: Next.js cache tags storage

R2 Bucket

Binding: NEXT_INC_CACHE_R2_BUCKET
Bucket: clickhouse-monitoring-inc-cache
Purpose: Large cache objects storage

Durable Objects

Binding: NEXT_CACHE_DO_QUEUE
Class: DOQueueHandler
Purpose: Background task processing

Troubleshooting

"The entry-point file at '.open-next/worker.js' was not found"

Cause: The build command did not run bun run cf:build to generate the .open-next/ directory.

Solutions:

Ensure the build command is bun install --frozen-lockfile && bun run cf:build
Check that GitHub Actions workflow runs successfully
Verify .open-next/ is not in .gitignore (it should be, but Cloudflare builds it fresh)