Can't find module "cloudflare:workers" when using RC with the Cloudflare Vite Plugin

[dan-gamble]

Which project does this relate to?

Router

Describe the bug

I've followed the build from scratch tutorial as well as the Cloudflare Hosting docs. All I've done is add a KV namespace and duplicated the button on the index.tsx to do a read/write from KV

// wrangler.json
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "tanstack-start-shopify",
	"compatibility_date": "2025-09-02",
	"compatibility_flags": [
		"nodejs_compat"
	],
	"main": "@tanstack/react-start/server-entry",
	"observability": {
		"enabled": true
	},
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "###"
		}
	]
}

// src/routes/index.tsx
import * as fs from "node:fs";
import { createFileRoute, useRouter } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { env } from "cloudflare:workers";

const FILE_PATH = "count.txt";
const KV_KEY = "count";

async function readFileCount() {
  return Number.parseInt(
    await fs.promises.readFile(FILE_PATH, "utf-8").catch(() => "0"),
    10,
  );
}

async function readKvCount() {
  return Number.parseInt((await env.KV.get(KV_KEY)) ?? "0", 10);
}

const getFileCount = createServerFn({ method: "GET" }).handler(() =>
  readFileCount(),
);

const getKvCount = createServerFn({ method: "GET" }).handler(() =>
  readKvCount(),
);

const updateFileCount = createServerFn({ method: "POST" })
  .inputValidator((count: number) => count)
  .handler(async ({ data }) => {
    const currentCount = await readFileCount();

    await fs.promises.writeFile(FILE_PATH, `${currentCount + data}`);
  });

const updateKvCount = createServerFn({ method: "POST" })
  .inputValidator((count: number) => count)
  .handler(async ({ data }) => {
    const currentCount = await readKvCount();

    await env.KV.put(KV_KEY, `${currentCount + data}`);
  });

export const Route = createFileRoute("/")({
  component: Home,
  loader: async () => await getFileCount(),
});

function Home() {
  const router = useRouter();
  const state = Route.useLoaderData();

  return (
    <div>
      <button
        type="button"
        onClick={() => {
          updateFileCount({ data: 1 }).then(() => router.invalidate());
        }}
      >
        FILE - Add 1 to {state}?
      </button>

      <button
        type="button"
        onClick={() => {
          updateKvCount({ data: 1 }).then(() => router.invalidate());
        }}
      >
        KV - Add 1 to {state}?
      </button>
    </div>
  );
}

// vite.config.ts
import { defineConfig } from "vite";
import tsConfigPaths from "vite-tsconfig-paths";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
  server: {
    port: 3000,
  },
  plugins: [tsConfigPaths(), tanstackStart(), cloudflare(), viteReact()],
});

Error

$ vite dev
                                                                                                                                                                                                                                                             
  VITE v7.1.7  ready in 1025 ms
                                                                                                                                                                                                                                                             
  ➜  Local:   http://localhost:3000/
  ➜  Network: use --host to expose
  ➜  Debug:   http://localhost:3000/__debug
  ➜  press h + enter to show help
[vite] connected.
Error: Cannot find module 'cloudflare:workers' imported from '/Users/dangamble/Code/tanstack-start-shopify/src/routes/index.tsx'
    at fetchModule (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/chunks/dep-Bm2ujbhY.js:34296:34)
    ... 8 lines matching cause stack trace ...
    at Object.invoke (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/module-runner.js:582:31) {
  cause: Error: Cannot find module 'cloudflare:workers' imported from '/Users/dangamble/Code/tanstack-start-shopify/src/routes/index.tsx'
      at fetchModule (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/chunks/dep-Bm2ujbhY.js:34296:34)
      at RunnableDevEnvironment.fetchModule (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/chunks/dep-Bm2ujbhY.js:35132:10)
      at fetchModule (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/chunks/dep-Bm2ujbhY.js:35101:16)
      at handleInvoke (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/chunks/dep-Bm2ujbhY.js:28480:27)
      at EventEmitter.listenerForInvokeHandler (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/chunks/dep-Bm2ujbhY.js:28539:19)
      at EventEmitter.emit (node:events:518:28)
      at EventEmitter.emit (node:domain:489:12)
      at Object.send (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/chunks/dep-Bm2ujbhY.js:18568:39)
      at Object.invoke (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/module-runner.js:533:31)
      at Object.invoke (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/module-runner.js:582:31) {
    code: 'ERR_MODULE_NOT_FOUND',
    runnerError: Error: RunnerError
        at reviveInvokeError (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/module-runner.js:474:64)
        at Object.invoke (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/module-runner.js:547:11)
        at async ModuleRunner.getModuleInformation (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/module-runner.js:1052:7)
        at async request (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/module-runner.js:1069:83)
        at async eval (/Users/dangamble/Code/tanstack-start-shopify/src/routes/index.tsx:4:1)
        at async ESModulesEvaluator.runInlinedModule (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/module-runner.js:905:3)
        at async ModuleRunner.directRequest (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/module-runner.js:1112:59)
        at async ModuleRunner.cachedRequest (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/module-runner.js:1030:73)
        at async eval (/Users/dangamble/Code/tanstack-start-shopify/src/routeTree.gen.ts:12:1)
        at async ESModulesEvaluator.runInlinedModule (file:///Users/dangamble/Code/tanstack-start-shopify/node_modules/vite/dist/node/module-runner.js:905:3)
  },
  status: 500,
  statusText: undefined,
  headers: undefined,
  data: undefined,
  body: undefined,
  unhandled: true
}
ReferenceError: Cannot access '__vite_ssr_import_1__' before initialization
    at Module.getRouter (/Users/dangamble/Code/tanstack-start-shopify/src/router.tsx:6:5)
    ... 2 lines matching cause stack trace ...
    at async eval (/Users/dangamble/Code/tanstack-start-shopify/node_modules/@tanstack/start-server-core/src/createStartHandler.ts:263:32) {
  cause: ReferenceError: Cannot access '__vite_ssr_import_1__' before initialization
      at Module.getRouter (/Users/dangamble/Code/tanstack-start-shopify/src/router.tsx:6:5)
      at getRouter (/Users/dangamble/Code/tanstack-start-shopify/node_modules/@tanstack/start-server-core/src/createStartHandler.ts:145:55)
      at async handleServerRoutes (/Users/dangamble/Code/tanstack-start-shopify/node_modules/@tanstack/start-server-core/src/createStartHandler.ts:375:18)
      at async eval (/Users/dangamble/Code/tanstack-start-shopify/node_modules/@tanstack/start-server-core/src/createStartHandler.ts:263:32),
  status: 500,
  statusText: undefined,
  headers: undefined,
  data: undefined,
  body: undefined,
  unhandled: true
}
ReferenceError: Cannot access '__vite_ssr_import_1__' before initialization
    at Module.getRouter (/Users/dangamble/Code/tanstack-start-shopify/src/router.tsx:6:5)
    ... 3 lines matching cause stack trace ...
    at async eval (/Users/dangamble/Code/tanstack-start-shopify/node_modules/@tanstack/start-server-core/src/createStartHandler.ts:263:32) {
  cause: ReferenceError: Cannot access '__vite_ssr_import_1__' before initialization
      at Module.getRouter (/Users/dangamble/Code/tanstack-start-shopify/src/router.tsx:6:5)
      at getRouter (/Users/dangamble/Code/tanstack-start-shopify/node_modules/@tanstack/start-server-core/src/createStartHandler.ts:145:55)
      at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
      at async handleServerRoutes (/Users/dangamble/Code/tanstack-start-shopify/node_modules/@tanstack/start-server-core/src/createStartHandler.ts:375:18)
      at async eval (/Users/dangamble/Code/tanstack-start-shopify/node_modules/@tanstack/start-server-core/src/createStartHandler.ts:263:32),
  status: 500,
  statusText: undefined,
  headers: undefined,
  data: undefined,
  body: undefined,
  unhandled: true
}

Your Example Website or App

https://github.com/dan-gamble/tanstack-start-cloudflare

Steps to Reproduce the Bug or Issue

1. Follow the "Build from scratch" tutorial
2. Follow the Cloudflare hosting tutorial
3. Add a KV
4. Try and use the import { env } from "cloudflare:workers"

Expected behavior

As a user I would expect the page to load with no errors

Screenshots or Videos

Platform

• Router / Start Version: RC
• OS: MacOS
• Browser: Arc
• Browser Version: 1.113
• Bundler: Vite
• Bundler Version: 7.1.3

Additional context

Opening this as #4687 was closed

[dan-gamble]

From following this

Adding the viteEnvironment option to the cloudflare() call fixes it. I did also change the order of the plugins around, I wasn't sure which of these 2 made the difference

// vite.config.ts
import { defineConfig } from "vite";
import tsConfigPaths from "vite-tsconfig-paths";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
  server: {
    port: 3000,
  },
  plugins: [
    cloudflare({
      viteEnvironment: { name: "ssr" },
    }),
    tsConfigPaths(),
    tanstackStart(),
    viteReact(),
  ],
});

[bachiitter]

still doesn't work on v1.132.6

[dan-gamble]

I have found adding the viteEnvironment: { name: "ssr" } means when adding Dev tools this breaks though. For now I'm just not using the dev tools

Edit
The above is documented in #5213

[schiller-manuel]

docs have been updated for this https://tanstack.com/start/latest/docs/framework/react/hosting#cloudflare-workers

[ourines]

https://tanstack.com/start/latest/docs/framework/react/hosting#cloudflare-workers

Still unable to use the Cloudflare Vite plugin correctly.

[schiller-manuel]

please follow this example: https://github.com/TanStack/router/tree/main/examples/react/start-basic-cloudflare