cloudflare / cloudflare/workers-sdk

[vitest-pool-workers] Can't resolve TanStack Start's @tanstack/react-start/server-entry when main points at it

Open
#14,937 1 comment 0 reactions 0 assignees View on GitHub
package:vitest
Dominant language
TypeScript
Stars
4.5k
Forks
1.5k
Avg merge
3d 8h
Merged PRs (30d)
187

Description

### What versions & operating system are you using?

```
System:
OS: macOS 26.6
CPU: (8) x64 Apple M1 Pro
Memory: 37.30 MB / 16.00 GB
Shell: 5.9 - /bin/zsh
Binaries:
Node: 26.3.1 - /usr/local/bin/node
Yarn: 1.22.22 - /usr/local/bin/yarn
npm: 11.16.0 - /usr/local/bin/npm
pnpm: 10.34.5 - /usr/local/bin/pnpm
bun: 1.3.14 - /usr/local/bin/bun
npmPackages:
@cloudflare/vite-plugin: ^1.26.0 => 1.49.0
@cloudflare/vitest-pool-workers: ^0.19.1 => 0.19.1
wrangler: ^4.70.0 => 4.116.0
```

### Please provide a link to a minimal reproduction

https://github.com/lorenzolewis/vpw-repro

### Describe the Bug

`wrangler.jsonc`'s `main` is set to `@tanstack/react-start/server-entry` — this is exactly the value Cloudflare's own [TanStack Start hosting guide](https://developers.cloudflare.com/workers/vite-plugin/tutorial/) instructs you to use:

```jsonc
{
"main": "@tanstack/react-start/server-entry"
}
```

```ts
// vite.config.ts
import { cloudflare } from "@cloudflare/vite-plugin"
import { tanstackStart } from "@tanstack/react-start/plugin/vite"
// ...
plugins: [cloudflare({ viteEnvironment: { name: "ssr" } }), tanstackStart(), /* ... */]
```

#### Steps to reproduce

1. `npx @tanstack/cli create my-app --framework react --deployment cloudflare` (or see repro repo).
2. Add `@cloudflare/vitest-pool-workers` and `vitest`, with a `vitest.config.ts` that follows the docs:
```ts
import { cloudflareTest } from "@cloudflare/vitest-pool-workers"
import { defineConfig } from "vitest/config"

export default defineConfig({
plugins: [cloudflareTest({ wrangler: { configPath: "./wrangler.jsonc" } })],
})
```
3. Add a test that calls `SELF.fetch(...)` from `cloudflare:test`.
4. `npx vitest run`.

#### Workaround (current)

Point `cloudflareTest({ main: ... })` at a stub file instead of the real entry:

```ts
// vitest.config.ts
cloudflareTest({ main: "./test/worker.ts" })
```

```ts
// test/worker.ts
export default {} satisfies ExportedHandler
```

#### Additional context from AI (if helpful)

`@tanstack/react-start/server-entry` is a *virtual module* created by TanStack Start's Vite plugin — it only resolves inside Vite's plugin pipeline. `@cloudflare/vite-plugin` understands this fine at `dev`/`build`/`deploy` time.

`@cloudflare/vitest-pool-workers` resolves `main` differently: it runs its own standalone esbuild-based static analysis (`guessWorkerExports`, in `src/pool/index.ts`) to infer `ctx.exports`, gated behind the `enable_ctx_exports` compat flag (default-on for `compatibility_date >= 2025-11-17`). esbuild has no Vite/plugin context, so it can't resolve the bare specifier and throws.

This isn't just a cosmetic warning. It happens in two stages:

1. **At pool startup**, the failure is caught and only logged as `[vpw:warn]` (export-guessing is best-effort), so nothing appears to break yet:
```
[vpw:warn] Failed to statically analyze the exports of the main Worker entry-point ".../@tanstack/react-start/server-entry"
[vpw:warn] More details: Error: Build failed with 1 error:
[vpw:warn] error: Could not resolve ".../@tanstack/react-start/server-entry"
```
2. **The moment any test actually dispatches a request into the runner Worker** (e.g. via `SELF.fetch(...)`, the API `cloudflare:test` provides specifically for integration-testing the real entry point), the same unresolved module is imported for real and throws, failing the test file outright:
```
Error: Cannot find module '.../@tanstack/react-start/server-entry' imported from cloudflare:test-...
❯ maybeHandleRunRequest .../@cloudflare/vitest-pool-workers/dist/worker/lib/cloudflare/test-internal.mjs:164:18
❯ __VITEST_POOL_WORKERS_RUNNER_DURABLE_OBJECT__.fetch index.mjs:850:20
```

### Please provide any relevant error logs

```
[vpw:warn] Failed to statically analyze the exports of the main Worker entry-point "/path/to/project/@tanstack/react-start/server-entry"
[vpw:warn] More details: Error: Build failed with 1 error:
[vpw:warn] error: Could not resolve "/path/to/project/@tanstack/react-start/server-entry"
❯ test/index.test.ts (0 test)

⎯⎯⎯⎯⎯⎯ Failed Suites 1 ⎯⎯⎯⎯⎯⎯⎯

FAIL test/index.test.ts [ test/index.test.ts ]
Error: Cannot find module '/path/to/project/@tanstack/react-start/server-entry' imported from cloudflare:test-b27f3b8c-5399-458d-b7cf-5cbd3eb5f7b9
❯ maybeHandleRunRequest /path/to/project/node_modules/@cloudflare/vitest-pool-workers/dist/worker/lib/cloudflare/test-internal.mjs:164:18
❯ __VITEST_POOL_WORKERS_RUNNER_DURABLE_OBJECT__.fetch index.mjs:850:20
```

Contributor guide

Open the contributing guide

Research direction

Start with src/pool/index.ts and the guessWorkerExports entry point, then reproduce the failure using the linked minimal reproduction and the documented SELF.fetch test. Trace how the configured main entry is analyzed at pool startup and imported during request dispatch; done means the TanStack Start entry no longer causes the integration test to fail while export handling remains correct.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
backend, testing
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.