Rsbuild Import Protection - Adapter Internals

Scope

This document covers the Rsbuild-specific orchestration around the shared import-protection core in src/import-protection/INTERNALS.md.

Rsbuild owns:

• post-transform enforcement through api.transform({ order: 'post' })
• virtual-module transport through VirtualModulesPlugin
• compilation-truth reporting in processAssets
• final graph reconstruction from Rspack compilation data
• the small build-only deferred queue for file violations that can disappear from the compiled graph

Shared AST analysis, rewrite logic, source extraction, usage lookup, source locations, trace formatting, and mock code generation are described in the shared internals doc.

Mental Model

Vite is primarily resolveId-driven. Rsbuild is primarily transform + processAssets-driven.

That difference explains most of the adapter divergence.

Rsbuild does not emulate the Vite pending-queue state machine. It relies more directly on post-transform code and final compilation truth.

Native Hook Shape

Import protection is attached through Rsbuild hooks, not a dedicated mini-plugin object:

1. onBeforeBuild
2. onBeforeDevCompile
3. modifyRspackConfig
4. transform(..., { order: 'post' })
5. processAssets(..., { stage: 'report' })

State Model

Per environment, Rsbuild keeps a smaller runtime state than Vite:

• resolveCache
• seenViolations
• buildTransformResults
• deferredFileViolations
• deferredFileViolationKeys

Shared state is for virtual module transport and compiler fs access:

• virtualModules
• vmPlugins
• readyVmPlugins
• inputFileSystems
• pendingWrites

Notably absent compared to Vite:

• no pendingViolations
• no postTransformImports
• no broad deferredBuildViolations
• no resolve-time dev reachability pipeline

Transform Phase

Rsbuild enforcement runs after the Start compiler in a post transform.

That matters because many compiler-safe imports are already stripped by the time import protection runs. This naturally suppresses a large class of false positives without a Vite-style pending verification pass.

The transform phase is responsible for:

• self-denial for forbidden files
• self-denial for marker-protected files in the wrong environment
• direct specifier rewrites to mock-edge modules
• build-time transformed/original source preloading for later diagnostics
• recording build-only deferred file violations when original unsafe usage may outlive a direct compiled graph edge

Virtual Module Transport

Rsbuild reuses the shared mock generators, but not the Vite id transport.

Instead it writes environment-scoped virtual files under:

<root>/node_modules/.virtual/import-protection/<env>/

The important forms are:

• mock-silent.mjs
• mock-runtime-<base64>.mjs
• mock-edge-<base64>.mjs

Writes may happen before the VirtualModulesPlugin instance is ready, so the adapter queues them and flushes during compilation setup.

Reporting Phase

processAssets({ stage: 'report' }) is the authoritative reporting step.

It reconstructs the final view of the compilation from Rspack data by:

1. building a TransformResultProvider from compilation.modules
2. rebuilding the active compilation graph from outgoing connections
3. reconstructing surviving specifier violations from compiled mock-edge files
4. reporting live file violations from active edges
5. reporting live marker violations from active edges plus original source
6. reporting deferred file violations only when both importer and target truly survived compilation

This is the core Rsbuild-native replacement for Vite's generateBundle verification plus dev pending-violation flow.

Why The Deferred Queue Is Narrow

Rsbuild only needs explicit build deferral for file violations whose direct edge may disappear after compilation.

Specifier violations are rediscovered from surviving mock-edge virtual files. Marker violations are rediscovered from live compiled edges.

Only file violations need extra bookkeeping when the final compiled graph can no longer show the original denied edge directly.

Source And Compilation APIs

The Rsbuild adapter intentionally prefers native Rspack APIs where possible.

Transform-time:

• ctx.resource
• ctx.context
• ctx.resolve(...)
• captured compiler.inputFileSystem.readFile(...)

Compilation-time:

• module.nameForCondition?.()
• module.resourceResolveData?.resource
• module.originalSource().sourceAndMap()
• sourcemap sourcesContent
• compilation.inputFileSystem.readFile(...)

This keeps the adapter closer to Rsbuild/Rspack truth and avoids falling back to Node fs when the compilation already has the needed data.

Marker Handling

Unlike Vite, Rsbuild does not introduce plugin-owned virtual marker modules for normal operation.

The real package marker files are used as source-level markers, and the adapter later infers marker kind from original source while reporting compiled edges.

Practical Maintainer Rule

When changing Rsbuild import protection, ask:

1. Can the change be expressed in shared analysis/rewrite/mock codegen instead?
2. If it is adapter-specific, is it really about post-transform enforcement, virtual-file transport, or compilation-time reporting?
3. Can final compilation truth answer the question more simply than adding a new pending state machine?