notes/tsx/node-integration.md
How tsx integrates with Node. The underlying Node evidence is owned by notes/node.
The current gates are defined in src/utils/node-features.ts.
| tsx feature | Node reference |
|---|---|
moduleRegister | Async module hooks |
moduleRegisterHooksCjsReload | CJS reload support |
esmLoadReadFile | CJS source from load hooks |
importAttributes | Import attributes |
importMetaPathProperties | import.meta path properties |
requireEsm | CJS requiring ESM |
requireEsmNoWarning | CJS requiring ESM |
cjsNamespaceModuleExports | CJS synthetic namespaces |
cjsNamespaceFromLoadHook | CJS source from load hooks |
requireEsmExtensionlessMjs | CJS requiring ESM |
wasmModules | WASM modules |
modulePackageMainResolution | Package main assertion fix |
cliTestFlag and testRunnerGlob | Test runner |
nativeTypeScript | Native type stripping |
tsx uses the async module.register() path below the CJS-reload-safe boundary and sync module.registerHooks() at or above it (selection, registration). The sync path requires the CJS reload handshake, not only the existence of registerHooks().
Node v22.22.3 is included in this gate through the reload-handshake backport (gate). Gate changes must run the CJS interop and watch suites at each newly supported boundary.
The async worker path adds measurable fixed startup cost. In the hooks-passthrough benchmark with 1000 modules on an M5 Pro, Node 24.10.0 async hooks took 200ms and Node 24.15.0 sync hooks took 145ms. The benchmark documentation is in scripts/benchmark/README.md.
tsx patches Module._resolveFilename, registers TypeScript extension handlers, and preserves cache identity across transformed data URLs and internal queries (registration). The integration points are:
module-resolve-filename/index.ts for path and alias resolution;interop-cjs-exports.ts and preserve-query.ts for CJS cache identity;module-extensions.ts for extension handlers;cjs-loader-state.ts for sync-hook CJS pass-through.Candidate hygiene avoids resolution candidates that cannot win before calling Node (ESM resolver). This reduces the cost of Node's eager CJS hint decoration while retaining Node as the final authority for package exports, symlinks, and format detection. The resolver-policy owner is module-resolution.md.
tsx transforms TypeScript before Node's CJS preparse stage so Node constructs the namespace from JavaScript source (load hook). parentImportsCommonJsExports coordinates resolve and load hooks when a parent needs CJS named or namespace exports.
For native require(esm) interop, tsx distinguishes accessor descriptors emitted for ESM exports from ordinary CJS data descriptors before honoring a module.exports escape hatch (extension handler). This preserves ordinary CJS objects that contain a literal module.exports key.
When esbuild rejects top-level await for CommonJS output, the extension handler recognizes the diagnostic only for module-system candidates that native require(esm) could load. It preserves esbuild's TransformError name, message, and source location, and adds Node's loader-facing ERR_REQUIRE_ESM or ERR_REQUIRE_ASYNC_MODULE code so callers can fall back to import() (Node contract). The shared transformer remains context-neutral, so this mapping does not change ESM loader diagnostics.
When Node provides module-typescript or commonjs-typescript, tsx preserves Node's module classification (load hook). When Node provides no format, tsx uses its compatibility resolver and legacy CommonJS default.
tsx remains responsible for transformation syntax Node does not support, extension and path behavior Node leaves to tools, and transformed CJS/ESM interop. Node's type-stripping limits are documented in notes/node/type-stripping.md.
When touching an integration boundary, confirm the matching Node mechanism and run a behavior-level test:
| Integration point | tsx site | Node mechanism |
|---|---|---|
| CJS preparse call stack | is-from-cjs-lexer.ts | CJS preparse |
| CJS lexer grammar | src/esm/hook/load.ts | CJS preparse |
| CJS cache identity | interop-cjs-exports.ts, preserve-query.ts | CJS cache |
| Extension dispatch | module-extensions.ts | Extension handlers |
| Sync resolve/load hooks | src/esm/api/register.ts, src/esm/hook/ | Module hooks |
| CJS reload handshake | src/esm/hook/load.ts | CJS reload support |