Integrating Cloudflare Workers with Vite in OpenCut: A Complete Guide to @cloudflare/vite-plugin

The OpenCut web application uses the @cloudflare/vite-plugin to bundle its TanStack React Start SSR app for Cloudflare Workers, configured via vite.config.ts and deployed with Wrangler using zero manual polyfills.

The OpenCut repository demonstrates a production-ready pattern for running server-side rendered React applications at the edge. By integrating Cloudflare Workers with Vite through the official @cloudflare/vite-plugin, the project achieves edge deployment without sacrificing the developer experience of Vite's hot module replacement and fast builds.

How the Integration Works

OpenCut's architecture relies on three coordinated configuration layers to bridge Vite's build pipeline with Cloudflare's Workers runtime. The Vite configuration in apps/web/vite.config.ts loads the Cloudflare plugin and switches the environment to SSR mode. The package dependency in apps/web/package.json pins the plugin version and provides deployment scripts. Finally, the Wrangler configuration in apps/web/wrangler.jsonc defines the server entry point and runtime compatibility flags.

When you execute npm run deploy, Vite generates an SSR bundle that Wrangler uploads to Cloudflare. The Worker then executes this bundle on every request, delivering HTML pre-rendered by the TanStack React Start server entry.

Configuring Vite for Cloudflare Workers

The core integration happens in apps/web/vite.config.ts. The configuration imports cloudflare from @cloudflare/vite-plugin and invokes it with { viteEnvironment: { name: 'ssr' } }. This parameter signals Vite to generate an ES module bundle optimized for the Workers sandbox, stripping client-only code like hot-module replacement and injecting Cloudflare-specific polyfills for fetch and Headers.

// apps/web/vite.config.ts
import { defineConfig } from 'vite';
import { devtools } from '@tanstack/devtools-vite';
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import viteReact from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';
import { cloudflare } from '@cloudflare/vite-plugin';

export default defineConfig({
  resolve: { tsconfigPaths: true },
  plugins: [
    devtools(),
    // Cloudflare Workers integration
    cloudflare({ viteEnvironment: { name: 'ssr' } }),
    tailwindcss(),
    tanstackStart(),
    viteReact(),
  ],
});

Source: apps/web/vite.config.ts

Dependency and Script Setup

The plugin is declared as a runtime dependency in apps/web/package.json alongside the deployment script that chains Vite's build step with Wrangler's upload command.

{
  "dependencies": {
    "@cloudflare/vite-plugin": "^1.26.0"
  },
  "scripts": {
    "deploy": "bun run build && wrangler deploy"
  }
}

Source: apps/web/package.json

Wrangler Configuration for SSR

The apps/web/wrangler.jsonc file tells Cloudflare how to execute the generated bundle. The "main" field points to @tanstack/react-start/server-entry, which serves as the Worker's entry point. The nodejs_compat compatibility flag is essential—it enables Node.js API polyfills required by the SSR pipeline.

{
  "$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
    }
  ]
}

Source: apps/web/wrangler.jsonc

Deployment Workflow

To deploy the application to Cloudflare's edge network, run the deployment script from the apps/web directory:

npm run deploy

This command executes vite build to generate the SSR bundle, followed by wrangler deploy to push the assets to Cloudflare Workers. Once deployed, requests to https://new.opencut.app are handled by the Worker executing the pre-rendered React application.

Benefits of the Cloudflare Vite Plugin

The @cloudflare/vite-plugin provides several optimizations that simplify edge deployment:

• Automatic polyfills – Injects Cloudflare-specific shims for web standards and Node.js APIs, eliminating manual compatibility layers.
• Optimized asset handling – Rewrites static asset URLs to leverage Cloudflare's KV cache where appropriate, reducing latency for end users.
• Environment awareness – The viteEnvironment: { name: 'ssr' } configuration ensures the build output targets the Workers runtime exclusively, removing browser-specific code paths from the server bundle.

Summary

• Configure @cloudflare/vite-plugin in apps/web/vite.config.ts with viteEnvironment: { name: 'ssr' } to enable Workers-compatible SSR bundling.
• Declare the plugin dependency in apps/web/package.json and use compatibility_flags: ["nodejs_compat"] in wrangler.jsonc for Node.js API support.
• Set the server entry to @tanstack/react-start/server-entry in wrangler.jsonc to execute the TanStack React Start SSR bundle on Cloudflare Workers.
• Deploy via npm run deploy, which builds the SSR bundle and pushes it to Cloudflare's edge network.

Frequently Asked Questions

What does setting viteEnvironment: { name: 'ssr' } do in the Cloudflare plugin?

It instructs Vite to output an ES module bundle optimized for server-side rendering, stripping client-only code like hot-module replacement and ensuring the output targets the Cloudflare Workers runtime rather than the browser.

Why is nodejs_compat required in wrangler.jsonc?

The TanStack React Start SSR bundle relies on Node.js APIs that are not native to the Workers JavaScript runtime. The nodejs_compat flag enables Cloudflare's polyfills for these APIs, allowing the server entry to execute without modification.

Can I use this setup for local development, or is it deployment-only?

The configuration supports both environments. Running npm run dev uses the same vite.config.ts with the Cloudflare plugin active, enabling local testing of Workers-specific behavior before executing npm run deploy for production.

Where is the server entry point defined for the Cloudflare Worker?

The entry point is specified in apps/web/wrangler.jsonc as "main": "@tanstack/react-start/server-entry". This path points to the SSR server bundle generated by Vite, which the plugin prepares for execution in the Workers sandbox.

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