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

> Learn to integrate Cloudflare Workers with Vite in OpenCut using @cloudflare/vite-plugin. This guide shows effortless SSR bundling for Cloudflare deployment with zero polyfills.

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

---

**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`](https://github.com/OpenCut-app/OpenCut/blob/main/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`](https://github.com/OpenCut-app/OpenCut/blob/main/apps/web/vite.config.ts) loads the Cloudflare plugin and switches the environment to SSR mode. The **package dependency** in [`apps/web/package.json`](https://github.com/OpenCut-app/OpenCut/blob/main/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`](https://github.com/OpenCut-app/OpenCut/blob/main/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`.

```typescript
// 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](https://github.com/OpenCut-app/OpenCut/blob/main/apps/web/vite.config.ts)*

## Dependency and Script Setup

The plugin is declared as a runtime dependency in [`apps/web/package.json`](https://github.com/OpenCut-app/OpenCut/blob/main/apps/web/package.json) alongside the deployment script that chains Vite's build step with Wrangler's upload command.

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

```

*Source: [apps/web/package.json](https://github.com/OpenCut-app/OpenCut/blob/main/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.

```jsonc
{
  "$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](https://github.com/OpenCut-app/OpenCut/blob/main/apps/web/wrangler.jsonc)*

## Deployment Workflow

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

```bash
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`](https://github.com/OpenCut-app/OpenCut/blob/main/apps/web/vite.config.ts) with `viteEnvironment: { name: 'ssr' }` to enable Workers-compatible SSR bundling.
- Declare the plugin dependency in [`apps/web/package.json`](https://github.com/OpenCut-app/OpenCut/blob/main/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`](https://github.com/OpenCut-app/OpenCut/blob/main/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.