Import Protection Plugin — Internal Technical Documentation

Overview

The import protection plugin prevents server-only code from leaking into client bundles (and vice versa). It operates as a Vite plugin that intercepts module resolution, detects violations, and either errors or replaces the offending module with a safe mock.

The plugin must handle two axes of configuration:

Plugin Architecture

importProtectionPlugin() returns two Vite plugins:

1. tanstack-start-core:import-protection (enforce: 'pre')

The main enforcement plugin. Hooks: applyToEnvironment, configResolved, configureServer, buildStart, hotUpdate, resolveId, load, and generateBundle. All violation detection starts in resolveId.

2. tanstack-start-core:import-protection-transform-cache

Runs after all enforce: 'pre' hooks (including the Start compiler). Caches transformed code and composed sourcemaps for accurate source-location mapping in violation messages. Also resolves post-transform imports and triggers processPendingViolations() for the dev mock deferral path.

In both build and dev modes, this plugin performs self-denial: when a file matches a deny pattern in the current environment (e.g. a .server.ts file transformed in the client environment), its entire content is replaced with a mock module. This is the core mechanism for preventing cross-environment cache contamination — resolveId never returns virtual module IDs for file-based violations, so there is nothing for third-party resolver caches (e.g. vite-tsconfig-paths) to leak across environments. In dev mode, the mock imports a mock-runtime module for runtime diagnostics; in build mode, the mock is fully self-contained.

See the Self-Denial Transform section below for a detailed walkthrough with code examples.

Violation Types

The False-Positive Problem

Barrel re-exports

A common pattern:

db/index.ts        →  export { getUsers } from './db.server'
                       export { userColumns } from './shared'

route.tsx          →  import { getUsers, userColumns } from '../db'
                       // getUsers used only in createServerFn().handler()
                       // userColumns used in JSX

At resolveId time, db/index.ts imports ./db.server — the plugin sees a .server file imported in the client environment. But the Start compiler strips the getUsers usage from the client bundle (it's inside a server fn handler), and Rollup's tree-shaking then eliminates the ./db.server dependency entirely.

No server code actually leaks. But without deferral, the plugin fires at resolveId time — before tree-shaking — producing a false positive.

Pre-transform resolves (server-fn-lookup)

During dev, Vite's fetchModule(?SERVER_FN_LOOKUP) call triggers resolves for analysing a module's exports. These are tracked via serverFnLookupModules and isPreTransformResolve. In dev mock mode, pre-transform violations are deferred like all other violations (verified via edge-survival and graph reachability). In dev error mode, they are silenced because no deferred verification path exists.

Violation Handling Flow

Central functions

• handleViolation(): Formats + reports (or silences) the violation. Returns a resolve result so resolveId can substitute the offending import: for file-based violations, returns the physical file path (self-denial handles the rest in transform); for specifier/marker violations, returns a mock-edge module ID. May also return undefined (suppressed by onViolation or silent+error in dev) or throw via ctx.error() (dev+error).
• reportOrDeferViolation(): Dispatch layer. Either defers (stores for later verification) or reports immediately, depending on shouldDefer.

shouldDefer logic

shouldDefer = isBuild || isDevMock

• Dev mock: ALL violations (including pre-transform resolves) are deferred to pendingViolations → verified via edge-survival and post-transform graph reachability in processPendingViolations(). Pre-transform violations are tagged with fromPreTransformResolve so the pending-violation processor knows to wait for post-transform data before emitting.
• Build (both mock and error): Defer to deferredBuildViolations → verify via tree-shaking survival in generateBundle.

All three violation types (file, specifier, AND marker) are deferred in build mode. Marker violations through barrels can also be false positives — e.g., if foo.ts has import 'server-only' and is re-exported through a barrel but never used in client code, tree-shaking eliminates foo.ts entirely. To enable generateBundle tracking for markers, resolveId returns the unique build mock ID instead of the marker module. This is transparent because marker imports are bare (import 'server-only' — no bindings), and the mock module is equally side-effect-free.

Dev Mode Strategy

Dev + Error

Violations fire immediately via ctx.error() in resolveId. No tree-shaking is available, so false positives for barrel patterns are expected and accepted. (Dev + error is typically used only during explicit validation.)

Pre-transform resolves (e.g. server-fn-lookup) are silenced in error mode because they fire before the Start compiler runs — imports inside .server() callbacks haven't been stripped yet, and error mode has no deferred verification path.

Dev + Mock

1. resolveId detects the violation and calls reportOrDeferViolation().
2. For file-based violations: handleViolation() returns the physical file path (same as build mode). The self-denial transform in the transform-cache plugin will replace the file's content with a dev mock module that imports mock-runtime for runtime diagnostics.
3. For specifier/marker violations: handleViolation() returns a mock-edge module ID so the dev server can serve a Proxy-based mock.
4. The violation is stored in pendingViolations keyed by the importer's file path.
5. The transform-cache plugin, after resolving post-transform imports, calls processPendingViolations().
6. processPendingViolations() first applies edge-survival: if post-transform import data is available for the importer, it checks whether the denied import survived the Start compiler transform. Imports stripped by the compiler (e.g. inside .server() callbacks) are discarded. For pre-transform violations (fromPreTransformResolve), the function waits until post-transform data is available before proceeding.
7. After edge-survival, processPendingViolations() checks graph reachability from entry points using only post-transform edges. If the violating importer is reachable → confirm (warn). If unreachable → discard. If unknown → keep pending or emit conservatively (warm-start fallback).

Warm-start stability guardrails:

• Resolve-time edges discovered through pre-transform paths (isPreTransformResolve, especially SERVER_FN_LOOKUP) are not recorded into the reachability graph.
• In 'unknown' reachability status, pre-transform pending violations are kept pending (not fallback-emitted) until non-lookup transform evidence is available.

This approach can't fully eliminate barrel false-positives in dev because there's no tree-shaking. The barrel's import of .server always resolves, and the barrel is reachable. This is a known and accepted limitation.

Dev mock modules

Dev violations are handled differently depending on their type:

• File-based violations use self-denial (same mechanism as build mode): the denied file's content is replaced by the transform-cache plugin with a mock that imports mock-runtime for runtime diagnostics. The export list comes from the denied file's AST (what it exports), generated by generateDevSelfDenialModule(). This approach avoids the cold-start problem where the importer's AST is unavailable at resolveId time, and prevents cross-environment cache contamination from third-party resolver plugins.

• Specifier/marker violations use mock-edge modules: each violation gets a per-importer mock edge module that explicitly exports the names the importer expects (extracted lazily by resolveExportsForDeniedSpecifier() which parses the importer's AST) and delegates to a runtime mock module that contains a recursive Proxy and optional runtime diagnostics.

Mock edge modules (in detail)

A mock edge module is a lightweight, auto-generated virtual module that sits between an importing file and a base mock module. Its purpose is to provide explicit ESM named exports so that bundlers (Rollup, Rolldown) and Vite's dev server can correctly resolve import { foo } from './denied.server' — even though the real module has been replaced by a mock.

Why they exist

The base mock module (\0tanstack-start-import-protection:mock) exports only a default export — a recursive Proxy. But consumers of the denied module may use named imports:

import { getSecret, initDb } from './credentials.server'

Without explicit named exports, this would fail: the bundler would complain that getSecret and initDb don't exist on the mock module. Using syntheticNamedExports: true in Rollup could solve this, but Rolldown (which Vite can now use) doesn't support it. Mock edge modules solve the problem portably by generating real ESM export statements.

Structure

Each mock edge module is identified by a virtual ID:

\0tanstack-start-import-protection:mock-edge:<BASE64_PAYLOAD>

The Base64URL payload encodes two fields:

• exports — the list of named export identifiers the importer needs
• runtimeId — the module ID of the backing mock to import from

When Vite's load hook encounters this virtual ID, loadMockEdgeModule() decodes the payload and generates code like this:

// Generated mock edge module for exports: ["getSecret", "initDb"]
import mock from '\0tanstack-start-import-protection:mock'
export const getSecret = mock.getSecret
export const initDb = mock.initDb
export default mock

Each mock.getSecret access returns the Proxy itself (the Proxy's get trap returns mock for any property), so the named exports are valid callable/ constructable values that won't crash at runtime.

How exports are determined

The export list comes from parsing the importer's AST — not the denied file's AST. The function resolveExportsForDeniedSpecifier() performs this:

1. Gets the importer's code from the transform cache or getModuleInfo.
2. Calls collectMockExportNamesBySource() to extract which names the importer uses from each import source (parses the AST internally):
   • Named imports: import { getSecret, initDb } from './creds.server' → ['getSecret', 'initDb']
   • Namespace member access: import * as creds from './creds.server' then creds.getSecret() → ['getSecret']
   • Default import member access: import creds from './creds.server' then creds.getSecret → ['getSecret']
   • Re-exports: export { getSecret } from './creds.server' → ['getSecret']
3. Caches the result per importer so multiple violations from the same file don't re-parse.

This "importer-driven" approach means the mock edge module only exports the names the consumer actually references — not all exports from the denied file.

Dev vs build mock edge modules

In dev, the backing runtimeId is a mock-runtime:BASE64 module that includes diagnostic metadata (environment, import path, trace). When the mock is accessed in the browser, it logs a console warning or error. For SSR or when mockAccess is 'off', the backing mock is the shared silent MOCK_MODULE_ID.

In build, the backing mock uses a unique counter ID (mock:build:0, mock:build:1, ...) so generateBundle can check whether each specific violation's mock survived tree-shaking.

Handling non-identifier export names

ES2022 allows string-keyed exports like export { x as "foo-bar" }. Mock edge modules handle these via an intermediate variable:

import mock from '\0tanstack-start-import-protection:mock'
export const validName = mock.validName
const __tss_str_0 = mock['foo-bar']
export { __tss_str_0 as 'foo-bar' }

The default export name is always filtered out (handled separately as export default mock).

File-based violations: self-denial (dev and build)

File-based violations (e.g. import './db.server' in client env) use self-denial in both dev and build modes. handleViolation() returns the physical file path, and the transform-cache plugin replaces the file's contents with a mock module.

• Build mode: Uses generateSelfContainedMockModule() — a fully self-contained mock with an inlined Proxy factory (no import statements). This is important because build-mode mocks must be tree-shakeable.

• Dev mode: Uses generateDevSelfDenialModule() — a mock that imports mock-runtime for runtime diagnostics (console warnings/errors when the mock is accessed in the browser). The mock-runtime module ID encodes violation metadata (environment, import path, trace).

Self-denial avoids creating virtual mock-edge module IDs that could contaminate third-party resolver caches across Vite environments.

Non-file violations: mock-edge modules (dev and build)

Specifier and marker violations use mock-edge modules because the denied specifier doesn't resolve to a physical file that could be "self-denied."

• Build mode: Each violation gets a per-violation mock edge module wrapping a unique base mock module (\0tanstack-start-import-protection:mock:build:N). The edge module re-exports the named exports the importer expects, ensuring compatibility with both Rollup and Rolldown (which doesn't support syntheticNamedExports).

• Dev mode: Each violation gets a per-importer mock edge module wrapping a mock-runtime module for runtime diagnostics.

Build Mode Strategy

The "mock first, verify later" pattern

Both mock and error build modes follow the same pattern:

1. resolveId: Call handleViolation({ silent: true }).

   • For file-based violations: Returns the physical file path. The self-denial transform will replace its content.
   • For specifier/marker violations: Generates a unique per-violation mock-edge module wrapping a base mock module (\0tanstack-start-import-protection:mock:build:N). Stores the violation + mock-edge ID in env.deferredBuildViolations. Returns the mock-edge ID.

2. transform (self-denial): For file-based violations, the transform-cache plugin detects that the current file is denied in this environment and replaces its content with a self-contained mock module (generateSelfContainedMockModule()).

3. load: For base mock modules, returns a silent Proxy-based mock. For mock-edge modules, returns code that imports from the base mock and re-exports the expected named bindings (e.g. export const Foo = mock.Foo).

4. Tree-shaking: The bundler processes the bundle normally. If no binding from the mock module is actually used at runtime, the modules are eliminated.

5. generateBundle: Inspect the output chunks. For each deferred violation, check whether its unique mock module ID appears in any chunk's modules.

   • Survived → real violation (the import wasn't tree-shaken away).
     • Error mode: ctx.error() — fail the build.
     • Mock mode: ctx.warn() — emit a warning.
   • Eliminated → false positive (tree-shaking removed it). Suppress silently.

Why unique mock IDs per violation?

The original RESOLVED_MOCK_MODULE_ID is a single shared virtual module used for all mock-mode violations. If multiple violations are deferred, we need to know which specific ones survived tree-shaking. A shared ID would tell us "something survived" but not which violation it corresponds to. Each violation gets a unique mock-edge module (wrapping a unique base mock ...mock:build:0, ...mock:build:1, etc.) to provide this granularity.

Why mocking doesn't affect tree-shaking

From the consumer's perspective, the import bindings are identical whether they point to the real module or the mock. The bundler tree-shakes based on binding usage, not module content. If a binding from the barrel's re-export of .server is unused after the Start compiler strips server fn handlers, tree-shaking eliminates it regardless of whether it points to real DB code or a Proxy mock.

Per-environment operation

generateBundle runs once per Vite environment (client, SSR, etc.). Each environment has its own EnvState with its own deferredBuildViolations array. The check only inspects chunks from THAT environment's bundle, ensuring correct per-environment verification.

Marker violations vs. file/specifier violations

* In dev mock, handleViolation internally returns the physical file path (stored as the deferred result in pendingViolations), but resolveId ignores it for markers and falls through to return the marker module ID. The file path is only used for deferral bookkeeping, not for module resolution.

State Management

EnvState (per Vite environment)

Key fields for violation handling:

• seenViolations: Set<string> — deduplication of logged violations.
• pendingViolations: Map<string, Array<PendingViolation>> — dev mock deferral. Keyed by importer file path.
• deferredBuildViolations: Array<DeferredBuildViolation> — build mode deferral. Each entry has { info, mockModuleId }.

Per-build/watch iteration, buildStart clears pendingViolations and resets deferredBuildViolations so deferred entries don't leak across rebuilds.

• graph: ImportGraph — import dependency graph for reachability checks.
• serverFnLookupModules: Set<string> — modules transitively loaded during server-fn analysis (false-positive suppression).

SharedState (cross-environment)

• fileMarkerKind: Map<string, 'server' | 'client'> — cached per-file marker detection. A file's directive is inherent to the file, not the environment.

Virtual Module IDs

Key Design Decisions

Why not just skip .server resolves in barrels?

The plugin doesn't know at resolveId time whether the barrel's re-export will survive tree-shaking. It can't inspect the consumer's usage — it only sees the barrel importing .server. Skipping it would miss real violations where the barrel's .server re-export IS used in client code.

How marker violations are deferred in build

Marker violations normally resolve to RESOLVED_MARKER_* (empty export {}), not a mock. To enable generateBundle tracking, in build mode resolveId returns the unique build mock ID instead of the marker module. This works because:

1. The marker import is bare (import 'server-only' — no bindings), so swapping the resolution to a mock module is transparent.
2. The mock module is side-effect-free, just like the marker module.
3. If the importer file survives tree-shaking, the mock module survives → generateBundle fires the violation. If the importer is tree-shaken away (e.g., barrel re-export of a marker-protected file that's never used), the mock is eliminated → violation suppressed.

Why accept false positives in dev?

Dev mode uses Vite's ESM dev server — no bundling, no tree-shaking. The barrel file's import of .server always resolves and is always reachable from entry points. The graph-reachability check in processPendingViolations can only eliminate violations where the importer becomes unreachable after the Start compiler transforms it, not where individual bindings are unused.

This is an accepted trade-off: dev mock mode warns about potential issues, build mode provides definitive answers via tree-shaking.

E2E Test Structure

Tests live in e2e/react-start/import-protection/ and e2e/react-start/import-protection-custom-config/:

Main test suite (import-protection/)

• Mock mode (default): globalSetup builds the app, captures build warnings to violations.build.json, starts a dev server capturing to violations.dev.json. Tests read these JSON files and assert.
• Error mode (BEHAVIOR=error): globalSetup runs the build expecting failure, captures exit code + output. Tests assert the build failed with the expected violation.
• False-positive test: The barrel-reexport test case verifies that a barrel re-exporting from both a .server file and a marker-protected file (foo.ts with import 'server-only'), where all server-only bindings are tree-shaken away, produces zero violations in the build log.

Custom-config test suite (import-protection-custom-config/)

Uses non-default deny patterns (**/*.backend.* / **/*.frontend.*) to verify that import protection works with user-configured file patterns. This ensures the plugin doesn't hardcode any assumption about .server/.client naming conventions. The vite.config.ts provides custom client.files and server.files arrays; no vite-tsconfig-paths is used.

Self-Denial Transform (In Detail)

The self-denial transform is the mechanism by which the plugin prevents cross- environment contamination without creating virtual module IDs that could leak through third-party resolver caches. It applies to file-based violations in both dev and build modes.

The problem it solves

In Vite 7+, client and SSR environments run within the same Vite process. Some plugins (e.g. vite-tsconfig-paths) maintain a global resolution cache shared across environments. If the import-protection plugin resolves a specifier to a virtual mock module ID (e.g. \0tanstack-start-import-protection:mock-edge:...) in the client environment, that virtual ID can leak into the SSR environment's cache. When the SSR environment later resolves the same specifier, it finds the cached virtual ID instead of the real file — breaking the server.

In dev mode, self-denial also solves a cold-start problem: on cold start (no .vite cache), the importer's AST is unavailable when resolveId runs (neither the transform cache nor getModuleInfo have content yet). If mock-edge module IDs were generated at resolveId time, the export list would be empty (since it's derived from parsing the importer), producing a mock with no named exports — causing runtime errors like does not provide an export named: 'getSecret'.

How it works

Instead of returning a virtual module ID from resolveId, the self-denial transform works at the transform stage:

1. resolveId: For file-based violations, handleViolation() returns the physical file path. The import resolves normally. No virtual ID is created.

2. transform-cache plugin: When the transform-cache hook processes a file, it checks whether the file matches any deny pattern for the current environment using checkFileDenial(). If the file is denied, the plugin:

   a. Extracts the file's named exports using collectNamedExports() (parses the AST internally). b. Build mode: Generates a self-contained mock module via generateSelfContainedMockModule() — no imports, inlined Proxy factory. c. Dev mode: Generates a dev mock module via generateDevSelfDenialModule() — imports mock-runtime for runtime diagnostics (console warnings/errors when the mock is accessed). d. Returns the mock code as the transform result, completely replacing the original file content.

3. Fallback: If AST parsing fails (e.g. due to syntax errors in the denied file), exportNames defaults to [] (empty) and the mock module has no named exports:

   • Build: generateSelfContainedMockModule([]).
   • Dev: generateDevSelfDenialModule([], runtimeId) where runtimeId is computed via mockRuntimeModuleIdFromViolation() (which may internally fall back to the shared silent MOCK_MODULE_ID for SSR or when mockAccess is 'off').

Code transformation example

Original file (src/lib/credentials.server.ts):

import { db } from './database'

export function getSecret(): string {
  return db.query('SELECT secret FROM config LIMIT 1')
}

export const API_KEY = process.env.API_KEY!

export default { getSecret, API_KEY }

After self-denial transform in build mode (client environment):

/* @__NO_SIDE_EFFECTS__ */
function createMock() {
  const handler = {
    get: (_, prop) => {
      if (prop === Symbol.toPrimitive) return () => 'MOCK'
      if (typeof prop === 'symbol') return undefined
      return mock
    },
    apply: () => mock,
    construct: () => mock,
  }
  const mock = /* @__PURE__ */ new Proxy(function () {}, handler)
  return mock
}
const mock = /* @__PURE__ */ createMock()
export const getSecret = mock.getSecret
export const API_KEY = mock.API_KEY
export default mock

After self-denial transform in dev mode (client environment):

import mock from '\0tanstack-start-import-protection:mock-runtime:eyJ...'
export const getSecret = mock.getSecret
export const API_KEY = mock.API_KEY
export default mock

The mock-runtime module ID encodes violation metadata (environment, importer, specifier, trace) as a Base64URL payload. When the mock is accessed in the browser, it logs a console warning or error with this metadata.

Key properties

Build-mode mock (generateSelfContainedMockModule):

• Self-contained: No import statements — the Proxy factory is inlined.
• Tree-shakeable: All exports are marked pure (@__NO_SIDE_EFFECTS__, @__PURE__), so the bundler can eliminate unused exports.

Dev-mode mock (generateDevSelfDenialModule):

• Runtime diagnostics: Imports mock-runtime which provides console warnings/errors when the mock is accessed in the browser.
• Lightweight: No inlined Proxy factory — delegates to the mock-runtime virtual module.

Both modes:

• Same export interface: Named exports match the original file's exports, so consumers' import bindings remain valid.
• Safe at runtime: Every access returns the same Proxy, which is callable, constructable, and returns "MOCK" when coerced to a string.
• Export accuracy from denied file: Unlike mock-edge modules (which parse the importer's AST), self-denial parses the denied file's own AST. This provides a safe over-approximation — all exports the file offers — and avoids the cold-start problem where the importer hasn't been transformed yet.

Why self-denial instead of virtual modules for file-based violations

When self-denial is NOT used

Self-denial only applies to file-based violations.

• Specifier violations (e.g. import '@tanstack/react-start/server'): These are bare specifiers, not file paths. They use virtual mock-edge module IDs because the specifier doesn't resolve to a physical file that could be "self-denied."
• Marker violations: Use virtual mock IDs in build mode for generateBundle tracking (see marker section above). In dev mode, markers resolve to the marker module ID directly.

Module Dependency Architecture

The import-protection plugin is structured to avoid heavy transitive dependencies in its utility modules:

constants.ts          ← lightweight (no heavy imports)
├── IMPORT_PROTECTION_DEBUG
├── KNOWN_SOURCE_EXTENSIONS
├── SERVER_FN_LOOKUP_QUERY  ← imports SERVER_FN_LOOKUP from parent constants.ts
└── VITE_BROWSER_VIRTUAL_PREFIX

defaults.ts           ← lightweight (type-only imports)
├── getDefaultImportProtectionRules
└── getMarkerSpecifiers

matchers.ts           ← picomatch only
├── compileMatcher
├── compileMatchers
└── matchesAny

utils.ts              ← vite + node:path + local constants
├── normalizeFilePath, stripViteQuery, ...
└── extractImportSources, dedupePatterns, ...

trace.ts              ← imports from utils only
├── ImportGraph
├── buildTrace
└── formatViolation

virtualModules.ts     ← imports ../utils (parent), ../constants (parent)
├── generateSelfContainedMockModule, generateDevSelfDenialModule
├── loadMockEdgeModule, loadMockRuntimeModule
└── MOCK_MODULE_ID, MOCK_EDGE_PREFIX, ...

plugin.ts             ← main plugin, imports everything above

The SERVER_FN_LOOKUP constant lives in the shared parent constants.ts (not in start-compiler-plugin/plugin.ts) to avoid pulling in @tanstack/start-server-core when unit-testing import-protection modules.