# Wrangler Configuration for Deploying OpenCut to Cloudflare Pages and Workers

> Configure Wrangler to deploy OpenCut to Cloudflare Pages and Workers. Use separate wranger.jsonc files, enable Node.js support, and set up custom domain routing for seamless deployment.

- Repository: [OpenCut.app/OpenCut](https://github.com/OpenCut-app/OpenCut)
- Tags: how-to-guide
- Published: 2026-06-23

---

**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:

```json
{
  "$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`](https://github.com/OpenCut-app/OpenCut/blob/main/apps/web/vite.config.ts), the configuration loads the Wrangler environment:

```typescript
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:

```bash

# 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:

```json
{
  "$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`](https://github.com/OpenCut-app/OpenCut/blob/main/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`](https://github.com/OpenCut-app/OpenCut/blob/main/apps/api/src/index.ts) implements the Cloudflare adapter pattern:

```typescript
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:

```bash

# 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`](https://github.com/OpenCut-app/OpenCut/blob/main/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`](https://github.com/OpenCut-app/OpenCut/blob/main/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`](https://github.com/OpenCut-app/OpenCut/blob/main/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.