notes/node/node-integration-points.md
tsx follows Node's loader behavior closely, including a few implementation details that are not formal public APIs. This file is a re-verification map: when a new Node line changes loader internals, check these points and update tests or code only when behavior actually changed.
| Integration point | tsx site | Node source | Behavior to re-verify |
|---|---|---|---|
cjsPreparseModuleExports stack frame | src/cjs/api/module-resolve-filename/is-from-cjs-lexer.ts | Function name in v24.15.0 translators.js#L381 | Whether tsx still identifies resolution initiated by Node's CJS named-export preparse path and applies query/cache handling only there. |
CJS lexer grammar for module.exports = { ... } | src/esm/hook/load.ts transform-before-preparse path; tests/fixtures.ts annotation fixture | Vendored JS grammar docs in v24.11.1 README.md#L7-L51; native Merve grammar docs in v24.14.0 merve.h#L82-L102 | Whether esbuild's dead-code CJS export annotation still produces detectable named exports. |
Module._cache keying by resolved filename/data URL | src/cjs/api/module-resolve-filename/interop-cjs-exports.ts, preserve-query.ts, src/cjs/api/module-extensions.ts | Cache lookup in v24.15.0 loader.js#L1250-L1256 and ESM-loader cache marker handling loader.js#L1297-L1308 | Whether data-URL transformed CJS modules and query-preserved modules still share the intended CJS identity and export parsing state. |
require.extensions / Module._extensions enumeration and longest-extension lookup | src/cjs/api/module-extensions.ts | Extension table initialization loader.js#L355; longest registered extension lookup loader.js#L591-L600; extension dispatch loader.js#L1545-L1553 | Whether tsx's CJS loader still receives explicit .ts/.tsx/.cts and unknown-explicit-extension cases the same way Node routes extension handlers. |
loadWithHooks/resolveWithHooks sync hook call sites | src/esm/api/register.ts, src/esm/hook/resolve.ts, src/esm/hook/load.ts | v24.15.0 customization_hooks.js#L365, customization_hooks.js#L408 | Whether sync-hook behavior still matches the assumptions in tsx's sync/async registration split. |
shouldBeReloadedByCJSLoader load/translate handshake | src/esm/hook/load.ts (shouldBeReloadedByCJSLoader result field) | v24.11.1 load.js#L144-L171, translators.js#L334-L363 | Whether transformed CJS still re-enters Module._load where tsx needs CJS cache, globals, and evaluation semantics. |
When touching any tsx site above, check the latest Node source for the corresponding integration point and prefer a runtime test when the behavior matters. This file is an index for what to re-verify; tests are the enforcement.