Wrangler Configuration for Deploying OpenCut to Cloudflare Pages and Workers

Deploy OpenCut to Cloudflare by configuring separate wrangler.jsonc files for the Pages frontend and Workers backend, using compatibility flags for Node.js support and custom domain routing.

The OpenCut application is architected as a split deployment where the web UI targets Cloudflare Pages and the API targets Cloudflare Workers. According to the OpenCut-app/OpenCut source code, both environments require distinct Wrangler configurations located in the apps/ directory to handle SSR rendering, edge function deployment, and runtime compatibility.

Web UI Configuration for Cloudflare Pages

The frontend application runs as a Cloudflare Pages project with server-side rendering (SSR) enabled through TanStack Start.

Wrangler Configuration File

Located at apps/web/wrangler.jsonc, the configuration defines the Pages project settings:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "opencut-web",
  "compatibility_date": "2025-09-02",
  "compatibility_flags": ["nodejs_compat"],
  "main": "@tanstack/react-start/server-entry",
  "routes": [
    {
      "pattern": "new.opencut.app",
      "custom_domain": true
    }
  ]
}

Key configuration details:

• compatibility_date – Set to 2025-09-02 to ensure the Pages runtime supports the required Node.js compatibility layer.
• compatibility_flags – The nodejs_compat flag enables Node.js polyfills required by npm dependencies.
• main – Points to the SSR entry point generated by @tanstack/react-start/server-entry.
• routes – Declares new.opencut.app as a custom domain, routing all traffic for that hostname to this Pages project.

Vite Integration

The build pipeline integrates Wrangler settings through the Cloudflare Vite plugin. In apps/web/vite.config.ts, the configuration loads the Wrangler environment:

import { defineConfig } from 'vite'
import { cloudflare } from '@cloudflare/vite-plugin'
import tailwindcss from '@tailwindcss/vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  resolve: { tsconfigPaths: true },
  plugins: [
    cloudflare({ viteEnvironment: { name: 'ssr' } }),
    tailwindcss(),
    tanstackStart(),
    viteReact(),
  ],
})

The cloudflare() plugin reads the wrangler.jsonc configuration during the build process, ensuring the SSR bundle is compatible with the Cloudflare Pages runtime.

Build and Deploy Commands

Deploy the web UI using the following workflow:

# Build the Pages asset bundle

moon run web:build

# Deploy to Cloudflare Pages

wrangler pages publish ./dist

The wrangler pages publish command automatically detects and applies the configuration from apps/web/wrangler.jsonc, including compatibility flags and custom domain routing.

API Configuration for Cloudflare Workers

The backend API runs as a Cloudflare Worker using the Elysia framework with Ahead-of-Time (AoT) compilation.

Wrangler Configuration File

The API configuration in apps/api/wrangler.jsonc is streamlined for edge function deployment:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "opencut-api",
  "main": "src/index.ts",
  "compatibility_date": "2025-06-01"
}

Critical settings:

• main – Points to src/index.ts, which exports the Elysia server instance wrapped with the Cloudflare Workers adapter.
• compatibility_date – Set to 2025-06-01, the earliest date supporting the AoT compilation required by Elysia's CloudflareAdapter.

Elysia Server Implementation

The server entry point at apps/api/src/index.ts implements the Cloudflare adapter pattern:

import { Elysia, t } from "elysia"
import { CloudflareAdapter } from "elysia/adapter/cloudflare-worker"

export default new Elysia({ adapter: CloudflareAdapter })
  .get("/", () => ({ status: "ok" }))
  .get("/health", () => ({ healthy: true, timestamp: new Date().toISOString() }))
  .post("/echo", ({ body }) => body, {
    body: t.Object({ message: t.String() }),
  })
  .compile()

The .compile() method triggers AoT compilation at startup, optimizing the worker for cold starts in the Cloudflare edge environment.

Build and Deploy Commands

Deploy the API worker with these commands:

# Transpile TypeScript and bundle via wrangler

moon run api:build

# Upload the worker to Cloudflare

wrangler deploy

The wrangler deploy command references apps/api/wrangler.jsonc to register the worker under the name opencut-api in your Cloudflare account.

Complete Deployment Workflow

Deploy the full OpenCut stack by executing these steps in sequence:

1. Build the web UI – moon run web:build generates the dist/ folder with SSR assets.
2. Publish the frontend – wrangler pages publish ./dist deploys to Cloudflare Pages using the web configuration.
3. Build the API – moon run api:build prepares the worker bundle.
4. Deploy the backend – wrangler deploy uploads the API to Cloudflare Workers.

Both deployments share the same Cloudflare account, enabling the frontend to call backend endpoints via the same domain when configured with appropriate routing rules in the Cloudflare dashboard.

Key Configuration Files Reference

File Path	Purpose
apps/web/wrangler.jsonc	Cloudflare Pages configuration with custom domain and Node.js compatibility flags.
apps/web/vite.config.ts	Vite build pipeline integrating the Cloudflare plugin for SSR.
apps/api/wrangler.jsonc	Cloudflare Workers configuration for the Elysia-based API.
apps/api/src/index.ts	Server implementation using CloudflareAdapter and AoT compilation.

Summary

• Separate configurations are required for the frontend (apps/web/wrangler.jsonc) and backend (apps/api/wrangler.jsonc) due to different Cloudflare targets.
• Node.js compatibility is enabled via the nodejs_compat flag in the Pages configuration to support npm packages.
• Custom domains are configured in the web Wrangler file using the routes array with custom_domain: true.
• AoT compilation in the API requires a compatibility date of at least 2025-06-01 for Elysia's Cloudflare adapter.
• Build orchestration uses moon commands for TypeScript compilation, while wrangler handles the actual deployment to edge infrastructure.

Frequently Asked Questions

What compatibility flags are required for OpenCut on Cloudflare?

The web UI requires the nodejs_compat flag in apps/web/wrangler.jsonc to enable Node.js polyfills for the React-based frontend. The API worker does not explicitly declare compatibility flags but relies on a compatibility date of 2025-06-01 to support Elysia's Ahead-of-Time compilation features.

How does the web UI connect to the API backend?

Both projects deploy to the same Cloudflare account. You can configure the frontend to call the backend by adding a route pattern to apps/web/wrangler.jsonc that proxies /api/* paths to the opencut-api worker, or by using separate subdomains with CORS configuration in apps/api/src/index.ts.

Can I test OpenCut locally before deploying?

Yes. Use wrangler dev --port 8787 to run the API worker locally, and wrangler pages dev ./dist to serve the Pages build locally. Both commands read their respective wrangler.jsonc files, ensuring local behavior matches production compatibility settings.

Where are the Wrangler configuration files located?

The configurations are split by application: apps/web/wrangler.jsonc controls the Cloudflare Pages deployment for the frontend, while apps/api/wrangler.jsonc manages the Cloudflare Workers deployment for the backend API. Both files use the JSONC format (JSON with comments) and reference the Wrangler config schema for validation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}