fix: import protection robustness

docs/start/framework/react/guide/import-protection.md

@@ -335,6 +335,14 @@ The same idea applies to `createIsomorphicFn()`: the compiler removes the non-ta
 
 If you see an import-protection violation for a file you expected to be "compiled away", check whether the import is referenced outside a compiler-recognized environment boundary (or is otherwise kept live by surviving code).
 
+## False Positives: Dev vs Build
+
+In **build mode**, the plugin defers violation checks until after tree-shaking. If an import is eliminated from the final bundle (e.g., a barrel re-exports a `.server` module but no client code actually uses that export), no violation is reported. This means build-time violations are definitive — if the build flags it, the import truly survived.
+
+In **dev mode**, there is no tree-shaking. The plugin uses graph reachability to filter violations, but it cannot determine whether individual bindings are unused. This means barrel re-exports of `.server` or marker-protected modules may produce warnings even when the server-only exports would be tree-shaken away in production. These dev warnings are informational — run a build to confirm whether the violation is real.
+
+The same applies to marker-protected files (`import '@tanstack/react-start/server-only'`). If a marked file is re-exported through a barrel but never consumed by client code, the build correctly suppresses the violation while dev may still warn.
+
 ## The `onViolation` Callback
 
 You can hook into violations for custom reporting or to override the verdict:

e2e/react-start/import-protection/src/routes/__root.tsx

@@ -34,6 +34,10 @@ function RootComponent() {
           <Link to="/client-only-jsx">Client-Only JSX</Link>
           {' | '}
           <Link to="/beforeload-leak">Beforeload Leak</Link>
+          {' | '}
+          <Link to="/component-server-leak">Component Server Leak</Link>
+          {' | '}
+          <Link to="/barrel-false-positive">Barrel False Positive</Link>
         </nav>
         <Outlet />
         <Scripts />

e2e/react-start/import-protection/src/routes/barrel-false-positive.tsx

@@ -0,0 +1,43 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+// Import from the barrel — NOT directly from .server.
+// `getUsers` (from ./db.server) is only used inside a server fn (compiler strips it).
+// `userColumns` (from ./shared) is a plain object used in JSX — not server-only.
+// Tree-shaking should eliminate the ./db.server dependency entirely from the
+// client bundle, so no import-protection violation should fire for it.
+import { getUsers, userColumns, type User } from '../violations/barrel-reexport'
+
+const fetchUsers = createServerFn().handler(async () => {
+  return getUsers()
+})
+
+export const Route = createFileRoute('/barrel-false-positive')({
+  loader: () => fetchUsers(),
+  component: BarrelFalsePositive,
+})
+
+function BarrelFalsePositive() {
+  const users = Route.useLoaderData()
+
+  return (
+    <div>
+      <h1 data-testid="barrel-heading">Barrel False Positive</h1>
+      <table>
+        <thead>
+          <tr>
+            <th data-testid="col-name">{userColumns.name}</th>
+            <th data-testid="col-email">{userColumns.email}</th>
+          </tr>
+        </thead>
+        <tbody>
+          {users.map((user: User) => (
+            <tr key={user.id}>
+              <td>{user.name}</td>
+              <td>{user.email}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}

e2e/react-start/import-protection/src/routes/component-server-leak.tsx

@@ -0,0 +1,19 @@
+import { createFileRoute } from '@tanstack/react-router'
+// This import is used ONLY inside the route component.
+// The router plugin code-splits the component into a lazy chunk,
+// moving this import into the split module.
+// Import protection must still catch this as a violation.
+import { getComponentSecret } from '../violations/db-credentials.server'
+
+export const Route = createFileRoute('/component-server-leak')({
+  component: ComponentServerLeak,
+})
+
+function ComponentServerLeak() {
+  return (
+    <div>
+      <h1 data-testid="component-leak-heading">Component Server Leak</h1>
+      <p data-testid="component-leak-secret">{getComponentSecret()}</p>
+    </div>
+  )
+}

e2e/react-start/import-protection/src/violations/barrel-reexport/db.server.ts

@@ -0,0 +1,26 @@
+/**
+ * Server-only database module.
+ * Only exports server-only values: getUsers (DB access) and User type.
+ * The side-effect (DATABASE_URL log) should NOT reach the client.
+ */
+
+const DATABASE_URL =
+  process.env.DATABASE_URL ?? 'postgres://admin:s3cret@localhost:5432/myapp'
+
+console.log(`[db] connecting to ${DATABASE_URL}`)
+
+export interface User {
+  id: number
+  name: string
+  email: string
+}
+
+const FAKE_USERS: Array<User> = [
+  { id: 1, name: 'Alice', email: 'alice@example.com' },
+  { id: 2, name: 'Bob', email: 'bob@example.com' },
+]
+
+export async function getUsers(): Promise<Array<User>> {
+  await new Promise((r) => setTimeout(r, 50))
+  return FAKE_USERS
+}

e2e/react-start/import-protection/src/violations/barrel-reexport/foo.ts

@@ -0,0 +1,11 @@
+/**
+ * Server-only module protected by the marker import pattern.
+ * Re-exported through the barrel (index.ts) but never imported by
+ * barrel-false-positive.tsx — tree-shaking eliminates it from the
+ * client bundle, so no import-protection violation should fire.
+ */
+import '@tanstack/react-start/server-only'
+
+export function foo(): string {
+  return 'server-only value from foo'
+}

e2e/react-start/import-protection/src/violations/barrel-reexport/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Barrel file — NOT a .server file itself.
+ * Re-exports from a .server module, a marker-protected module, and a shared module.
+ *
+ * The key scenario: a consumer imports { getUsers, userColumns } from here.
+ * - getUsers comes from ./db.server (server-only via file suffix)
+ * - foo comes from ./foo (server-only via marker import)
+ * - userColumns comes from ./shared (client-safe)
+ *
+ * If getUsers is only used inside a createServerFn handler (compiler strips it),
+ * and foo is never imported by the consumer at all, tree-shaking should eliminate
+ * both ./db.server and ./foo from the client bundle — so the import-protection
+ * plugin should NOT fire violations for either.
+ */
+export { getUsers, type User } from './db.server'
+export { foo } from './foo'
+export { userColumns } from './shared'

e2e/react-start/import-protection/src/violations/barrel-reexport/shared.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared (non-server) module with client-safe values.
+ * These are safe to use on the client.
+ */
+import type { User } from './db.server'
+
+export const userColumns = {
+  name: 'Full Name',
+  email: 'Email Address',
+} as const
+
+/** Placeholder for when no users have loaded yet. */
+export const emptyUser: User = { id: 0, name: '', email: '' }

e2e/react-start/import-protection/src/violations/db-credentials.server.ts

@@ -0,0 +1,11 @@
+/**
+ * Server-only secret used exclusively inside a route component.
+ * The route component is code-split by the router plugin into a separate
+ * lazy chunk, so the import to this file ends up in the split module —
+ * NOT the original route file.  Import protection must still detect this.
+ */
+export const COMPONENT_SECRET = 'component-only-server-secret-99999'
+
+export function getComponentSecret() {
+  return COMPONENT_SECRET
+}

e2e/react-start/import-protection/tests/error-mode.setup.ts

@@ -104,6 +104,7 @@ const routes = [
   '/client-only-violations',
   '/client-only-jsx',
   '/beforeload-leak',
+  '/barrel-false-positive',
 ]
 
 async function captureDev(cwd: string): Promise<void> {

e2e/react-start/import-protection/tests/import-protection.spec.ts

@@ -540,3 +540,93 @@ for (const mode of ['dev', 'dev.warm'] as const) {
     expect(lookupHits).toEqual([])
   })
 }
+
+// Component-level server leak: the .server import is used exclusively inside
+// the route component function, which is code-split by the router plugin into
+// a separate lazy chunk.  Import protection must still detect this.
+
+test('component-server-leak route loads in mock mode', async ({ page }) => {
+  await page.goto('/component-server-leak')
+  await expect(page.getByTestId('component-leak-heading')).toContainText(
+    'Component Server Leak',
+  )
+})
+
+for (const mode of ['build', 'dev', 'dev.warm'] as const) {
+  test(`component-server-leak: .server import inside code-split component is caught in ${mode}`, async () => {
+    const violations = await readViolations(mode)
+
+    const hits = violations.filter(
+      (v) =>
+        v.envType === 'client' &&
+        (v.specifier.includes('db-credentials.server') ||
+          v.resolved?.includes('db-credentials.server') ||
+          v.importer.includes('db-credentials.server') ||
+          v.trace.some(
+            (s) =>
+              s.file.includes('db-credentials.server') ||
+              s.file.includes('component-server-leak'),
+          )),
+    )
+
+    expect(hits.length).toBeGreaterThanOrEqual(1)
+  })
+}
+
+// Barrel re-export false positive: the barrel re-exports from a .server
+// module AND a marker-protected module (foo.ts with `import 'server-only'`),
+// but the component only uses values that would be tree-shaken away
+// (getUsers inside createServerFn) or originate from a safe source, and
+// never imports foo at all. Both the .server module and the marker module
+// should NOT survive tree-shaking in the client bundle, so import-protection
+// must NOT flag violations for either in build mode.
+// In dev mode there is no tree-shaking so the violation is expected (mock).
+
+test('barrel-false-positive route loads in mock mode', async ({ page }) => {
+  await page.goto('/barrel-false-positive')
+  await expect(page.getByTestId('barrel-heading')).toContainText(
+    'Barrel False Positive',
+  )
+})
+
+test('no false positive for barrel-reexport .server pattern in build', async () => {
+  const violations = await readViolations('build')
+
+  const barrelHits = violations.filter(
+    (v) =>
+      v.envType === 'client' &&
+      (v.importer.includes('barrel-reexport') ||
+        v.importer.includes('barrel-false-positive') ||
+        v.specifier.includes('db.server') ||
+        v.resolved?.includes('barrel-reexport') ||
+        v.trace.some(
+          (s) =>
+            s.file.includes('barrel-reexport') ||
+            s.file.includes('barrel-false-positive'),
+        )),
+  )
+
+  expect(barrelHits).toEqual([])
+})
+
+test('no false positive for barrel-reexport marker pattern in build', async () => {
+  const violations = await readViolations('build')
+
+  // foo.ts uses `import '@tanstack/react-start/server-only'` marker and is
+  // re-exported through the barrel, but never imported by the route.
+  // Tree-shaking should eliminate it — no marker violation should fire.
+  const markerHits = violations.filter(
+    (v) =>
+      v.envType === 'client' &&
+      (v.specifier.includes('server-only') ||
+        v.specifier.includes('foo') ||
+        v.resolved?.includes('foo')) &&
+      v.trace.some(
+        (s) =>
+          s.file.includes('barrel-reexport') ||
+          s.file.includes('barrel-false-positive'),
+      ),
+  )
+
+  expect(markerHits).toEqual([])
+})

e2e/react-start/import-protection/tests/violations.setup.ts

@@ -79,6 +79,8 @@ const routes = [
   '/client-only-violations',
   '/client-only-jsx',
   '/beforeload-leak',
+  '/component-server-leak',
+  '/barrel-false-positive',
 ]
 
 async function navigateAllRoutes(