From 9af54a337fe6bc727e8af77bf4ed45fc287bf3bb Mon Sep 17 00:00:00 2001 From: Sheraff Date: Sun, 25 Oct 2026 12:23:12 +0100 Subject: [PATCH] test(start-plugin-core): client-only imports never reach the server A browser-only package (it reads window when it loads) that only a createClientOnlyFn body and an isomorphic .client() read, through a diamond and a cycle of helpers, never loads on the server: in dev (the SSR environment) and in Vite and Rsbuild builds, where the server build must neither bundle it nor warn about its importer, and SSR runs. A new S2 pin covers the server twin of the class rows: a class only a client-only fn uses keeps its client-only import on the server today. Co-Authored-By: Claude Opus 5.5 --- .../compiler-test-utils/oracle/KNOWN-BUGS.md | 12 +++--- .../start-build-client-only-imports.test.ts | 41 +++++++++++++++++-- .../tests/known-bugs-start-compiler.test.ts | 21 ++++++++++ .../tests/start-compiler-factories.test.ts | 34 +++++++++++++++ 4 files changed, 100 insertions(+), 8 deletions(-) diff --git a/packages/compiler-test-utils/oracle/KNOWN-BUGS.md b/packages/compiler-test-utils/oracle/KNOWN-BUGS.md index 73341d933a..a39d9275e5 100644 --- a/packages/compiler-test-utils/oracle/KNOWN-BUGS.md +++ b/packages/compiler-test-utils/oracle/KNOWN-BUGS.md @@ -7,7 +7,7 @@ One entry per root cause: the bug, the SPEC clause, the pins (`file` and test na `$name`, `%s` and `${…}` are table-row placeholders), and what a fix must achieve. The test comment (`Bug:`, `Impact:`) has the details. "Cause" files name today's implementation; a rewrite may have no such file. -Totals: 376 pin sites in 103 test files (a table test counts once; Vitest counts each row). +Totals: 377 pin sites in 103 test files (a table test counts once; Vitest counts each row). Pins whose input picks a name today's compiler generates (S6) flip with a compiler that generates other names. The adaptive pins next to them, which read the names a compiler actually generates, are the real check. @@ -40,13 +40,15 @@ compiles its JSX under the runtime the untouched file has, and keeps the factory **S2. Dead-code elimination keeps what only types or non-reads mention, and never removes some declaration kinds.** babel-dead-code-elimination counts `typeof x` type queries, TypeScript-only positions (enum members, overload and constructor parameters) and a local of a function's own name as reads, and never removes classes, enums, namespaces, -overloaded functions or redeclared `var`s. Server-only imports then stay on the client. SPEC J4.12, J2.5. Fix: code -only server code (or only types) reads is gone from the client, with its imports. 9 pins: +overloaded functions or redeclared `var`s. Server-only imports then stay on the client (and client-only imports on +the server). SPEC J4.12, J4.11, J2.5, G16. Fix: code only server code (or only types) reads is gone from the client, +with its imports, and code only client-only code reads is gone from the server. 10 pins: - `start-plugin-core/tests/known-bugs-start-compiler.test.ts`: "client: $name does not load its server-only import"; "client: a server-only import last mentioned by a type alias is not loaded with verbatimModuleSyntax"; "client: a validator schema that a type alias reads with typeof is not loaded"; "ssr: a declaration a client-only fn reads and - a type alias reads with typeof is not loaded". + a type alias reads with typeof is not loaded"; "ssr: a class only a client-only fn uses does not load its + client-only import". - `start-plugin-core/tests/integration/known-bugs-start-compiler.test.ts`: "client: the server-only module of a class only server code uses is not bundled"; "client: a server-only module a type mentions is not bundled with verbatimModuleSyntax". @@ -415,7 +417,7 @@ Paths under `router-plugin/tests/`. - **With options in a variable, the HMR transform declares the component binding after the object that reads it.** SPEC G1. `known-bugs-route-hmr.test.ts`: "route options in a variable ($name) evaluate to a route with a component". -## J4 Start environment separation (85 pins: 67 below, 18 in S1–S6) +## J4 Start environment separation (86 pins: 67 below, 19 in S1–S6) Paths under `start-plugin-core/tests/` unless noted. diff --git a/packages/start-plugin-core/tests/integration/start-build-client-only-imports.test.ts b/packages/start-plugin-core/tests/integration/start-build-client-only-imports.test.ts index cde5359690..64603bda27 100644 --- a/packages/start-plugin-core/tests/integration/start-build-client-only-imports.test.ts +++ b/packages/start-plugin-core/tests/integration/start-build-client-only-imports.test.ts @@ -4,9 +4,13 @@ * client-only code, are eliminated from the server build: a default-config * Start build reports no import-protection violation, the server bundle * holds none of their code, and each environment runs its implementation - * (SPEC J4.11, §5.12). + * (SPEC J4.11, §5.12). So is an installed browser-only package (it reads + * `window` when it loads) that only client-only code reads, through a + * diamond and a cycle of helpers: the server build neither bundles nor + * imports it, and reports nothing about it (G16). */ import { afterAll, beforeAll, describe, expect, test } from 'vitest' +import { findDiagnostics } from '@tanstack/compiler-test-utils/diagnostics' import { buildStart, startBundlers } from '../build-harness' import { reportedViolations } from '../importProtection/start-apps' import type { StartBuild } from '../build-harness' @@ -14,6 +18,14 @@ import type { StartBuild } from '../build-harness' const timeout = 60_000 const files = { + 'node_modules/browser-lib/package.json': JSON.stringify({ + name: 'browser-lib', + type: 'module', + exports: './index.js', + }), + 'node_modules/browser-lib/index.js': `const width = window.innerWidth +export const measure = () => 'MARK_BROWSER_LIB:' + typeof width +`, 'src/chart.client.ts': `export const draw = () => 'MARK_CHART'\n`, 'src/paint.ts': `import '@tanstack/react-start/client-only' export const paint = () => 'MARK_PAINT' @@ -21,10 +33,20 @@ export const paint = () => 'MARK_PAINT' 'src/entry.ts': `import { createClientOnlyFn, createIsomorphicFn } from '@tanstack/react-start' import { draw } from './chart.client' import { paint } from './paint' +import { measure } from 'browser-lib' +const measured = () => measure() +const left = () => measured() +const right = () => measured() +function ping(n: number): string { return n > 0 ? pong(n - 1) : left() + right() } +function pong(n: number): string { return n > 0 ? ping(n - 1) : '' } export const render = createClientOnlyFn(() => draw()) export const repaint = createIsomorphicFn() .server(() => 'server') .client(() => paint()) +export const size = createClientOnlyFn(() => measure()) +export const resize = createIsomorphicFn() + .server(() => 'server') + .client(() => ping(2)) `, } @@ -39,7 +61,7 @@ const run = `const settle = (fn) => { return { thrown: { name: error.name, message: error.message } } } } -return [settle(entry.render), settle(entry.repaint)]` +return [settle(entry.render), settle(entry.repaint), settle(entry.size), settle(entry.resize)]` describe.each(startBundlers)('%s build', (bundler) => { let build: StartBuild @@ -69,17 +91,30 @@ describe.each(startBundlers)('%s build', (bundler) => { expect([ build.ssr.where('MARK_CHART'), build.ssr.where('MARK_PAINT'), - ]).toEqual(['nowhere', 'nowhere']) + build.ssr.where('MARK_BROWSER_LIB'), + ]).toEqual(['nowhere', 'nowhere', 'nowhere']) + // (nothing about the module that imports them either) + expect( + findDiagnostics(build.ssr.warnings, { + file: 'src/entry.ts', + root: build.root, + }), + ).toEqual([]) }) test('each environment runs its implementation', async () => { expect((await build.client.run(run)).result).toEqual([ 'MARK_CHART', 'MARK_PAINT', + 'MARK_BROWSER_LIB:number', + 'MARK_BROWSER_LIB:numberMARK_BROWSER_LIB:number', ]) + // The server build loads (and would crash on) no browser-only package. expect((await build.ssr.run(run)).result).toEqual([ { thrown: expect.anything() }, 'server', + { thrown: expect.anything() }, + 'server', ]) }) }) diff --git a/packages/start-plugin-core/tests/known-bugs-start-compiler.test.ts b/packages/start-plugin-core/tests/known-bugs-start-compiler.test.ts index 2c49770fb2..7f570645d8 100644 --- a/packages/start-plugin-core/tests/known-bugs-start-compiler.test.ts +++ b/packages/start-plugin-core/tests/known-bugs-start-compiler.test.ts @@ -1649,4 +1649,25 @@ export const draw = createClientOnlyFn(() => chart.draw())` expectNotLoaded(await startCase.serverLoads(), ['./chart.client']) }, ) + + // Bug: the server twin of the class rows of "client: $name does not load + // its server-only import" above (dead-code elimination never removes a + // class declaration): a class only a client-only implementation uses + // stays in the SSR output with its client-only import (SPEC J4.11, G16). + // Impact: the server loads the client-only module and runs its top-level + // code; a browser-only package that reads `window` when it loads crashes + // SSR (Vite dev and build, Rsbuild build). + // Source: review (dead-code investigation, server direction). + test.fails( + 'ssr: a class only a client-only fn uses does not load its client-only import', + async () => { + const startCase = + await erasedCase(`import { createClientOnlyFn } from '@tanstack/react-start' +import { createChart } from './chart.client' +class Chart { draw() { return createChart().draw() } } +export const draw = createClientOnlyFn(() => new Chart().draw())`) + expectNotLoaded(await startCase.serverLoads(), ['./chart.client']) + expect(await inPage(startCase, 'return module.draw()')).toBe('drawn') + }, + ) }) diff --git a/packages/start-plugin-core/tests/start-compiler-factories.test.ts b/packages/start-plugin-core/tests/start-compiler-factories.test.ts index de10f70c5d..4d998b31f6 100644 --- a/packages/start-plugin-core/tests/start-compiler-factories.test.ts +++ b/packages/start-plugin-core/tests/start-compiler-factories.test.ts @@ -148,6 +148,40 @@ export { serverValue as exposed }`, ]) }) + // An installed browser-only package (it reads `window` when it loads) + // that only client-only code reads, through a diamond and a cycle of + // helpers, never loads on the server, where it would crash (SPEC J4.11, + // G16). The production twin: integration/start-build-client-only-imports.test.ts. + test('dev: the SSR environment does not load a browser-only package only client-only code reads', async () => { + const served = await serve( + `import { createClientOnlyFn, createIsomorphicFn } from '@tanstack/react-start' +import { measure } from 'browser-lib' +const measured = () => measure() +const left = () => measured() +const right = () => measured() +function ping(n: number): string { return n > 0 ? pong(n - 1) : left() + right() } +function pong(n: number): string { return n > 0 ? ping(n - 1) : '' } +export const size = createClientOnlyFn(() => measure()) +export const resize = createIsomorphicFn().server(() => 'server').client(() => ping(2))`, + { + 'node_modules/browser-lib/package.json': JSON.stringify({ + name: 'browser-lib', + type: 'module', + exports: './index.js', + }), + 'node_modules/browser-lib/index.js': `const width = window.innerWidth +export const measure = () => 'measure:' + typeof width +`, + }, + ) + expectNotLoaded(await served.serverLoads(), ['browser-lib']) + expect( + await inPage(served, 'return [module.size(), module.resize()]'), + ).toEqual(['measure:number', 'measure:numbermeasure:number']) + const ssr = await served.ssr() + expect([settle(ssr.size), ssr.resize()]).toEqual([throwsError, 'server']) + }) + // Source: Waku vite-plugin-allow-server.test.ts "handles default allowServer // export", "stubs default exports while preserving allowServer dependencies" test.each([