@contrast/esm-hooks
ECMAScript module (ESM) loading and instrumentation for the Contrast Node.js
agent. You don't use this package directly. The agent's ESM entry point loads
it when an application starts with node --import @contrast/agent (or
--loader on Node.js 18.7 to 18.18). See the
@contrast/agent README for how to start an application.
How it works
The hooks install after the agent onboards with Contrast, so they know whether
Assess, Protect, or both are active. When Module.register() is available, the
hooks run on Node's loader thread. Otherwise they are exported for the
--loader entry point. import-in-the-middle is registered earlier, as soon as
esm-hooks is composed onto core, and only wraps a short list of packages
(wrapPackages).
- Resolve hook (
lib/hooks.mjs) redirects modules that need instrumentation to wrappers underlib/redirects/(builtin/,cjs/,esm/), tagging the URL with?csi-flag=builtin,commonjs, ormodule. - Load hook (
lib/hooks.mjs) serves those redirect files and source rewritten by@contrast/rewriter. - The loader thread and the main thread communicate over a
MessageChannel(lib/post-message/).
Debugging
Set CSI_HOOKS_LOG to a bitmask to log hook activity:
| Value | Logs |
|---|---|
1 | ESM load() and CJS Module._load() calls |
2 | ESM resolve() calls |
4 | every CJS require() and compile |
Combine bits to log more than one, e.g. CSI_HOOKS_LOG=3 for load and resolve.