node-hook

library1.0.0jsnpmunverified

node-hook is a low-level utility for intercepting and transforming JavaScript source code before it is loaded by Node.js's CommonJS `require` mechanism. It allows developers to register a synchronous function that receives the raw source and filename, returning a modified source string for immediate evaluation. The current stable version is 1.0.0, released in 2017. Due to its age and reliance on Node.js's CommonJS module loader, it is largely incompatible with modern ES Modules (ESM) environments. Its release cadence was infrequent, with the last update several years ago. Key differentiators include its direct manipulation of `Module._extensions['.js']` for simple, synchronous source transforms, unlike more complex bundlers or build tools, making it suitable for runtime code instrumentation or on-the-fly transpilation in legacy CommonJS applications.

devops testing

npm install node-hook

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-HOOK

node-hook

devopsjavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

hook

✓ const hook = require('node-hook');

✗ import hook from 'node-hook';

node-hook is a CommonJS module and must be imported using `require()`. It does not support ES module `import` syntax.

hook.hook

✓ const { hook } = require('node-hook');

✗ const hook = require('node-hook').hook();

The `hook` method is a property of the default export. Destructuring or direct property access is the correct usage. Calling it as a function without arguments will fail.

hook.unhook

✓ const { unhook } = require('node-hook');

Used to remove a previously registered transform function for a given file extension.

This quickstart demonstrates how to register a source code transformation using `node-hook` for `.js` files. It shows how to apply a function that logs the processed filename and modifies the module's export, then unhooks the transform. It also highlights Node.js's module caching behavior.

const { hook, unhook } = require('node-hook'); const path = require('path'); const fs = require('fs'); // Create a dummy file to be required const dummyFilePath = path.join(__dirname, 'dummy.js'); fs.writeFileSync(dummyFilePath, 'module.exports = { message: "Hello from dummy!" };'); console.log('--- Registering hook ---'); // Register a transform function to log the filename and modify source function logAndModifySource(source, filename) { if (filename === dummyFilePath) { console.log(`[HOOK] Processing: ${filename}`); return `console.log('Transformed source for ${path.basename(filename)}');\n${source}\nmodule.exports.transformed = true;`; } return source; } hook('.js', logAndModifySource); console.log('--- Requiring dummy.js ---'); const dummyModule = require('./dummy'); console.log('--- Dummy module content ---'); console.log(dummyModule); console.log('--- Unhooking .js ---'); unhook('.js'); // Removes the transform console.log('--- Requiring dummy.js again (should use cached version) ---'); const dummyModuleCached = require('./dummy'); console.log(dummyModuleCached); // Clean up dummy file fs.unlinkSync(dummyFilePath);

Debug

Known issues

breakingVersion 1.0.0 introduced breaking changes; however, the specific details beyond 'release 1.0.0 closes #11' are not documented. Users upgrading from pre-1.0.0 versions should review their usage patterns carefully. Given the project's age, this is primarily a historical note.

fix

Review the commit history and issue tracker for '#11' if migrating from very old versions. For new projects, treat 1.0.0 as the baseline.

affects: >=1.0.0

gotchaNode.js caches compiled modules. If you apply a hook and then `require` the same file again, the cached version will be returned, and your transform function will not be re-applied. This can lead to unexpected behavior where changes aren't reflected.

fix

To force a module to reload and re-apply transforms, you must delete its entry from `require.cache` before calling `require()` again, e.g., `delete require.cache[require.resolve('./your-module')]`.

affects: >=0.1.0

breakingnode-hook operates exclusively on Node.js's CommonJS `require` mechanism. It is fundamentally incompatible with ES Modules (ESM) `import` statements and module loading processes. Attempting to use it in an ESM project or to hook ESM files will not work as intended.

fix

Use alternative tools like custom loaders (`--experimental-loader`) for Node.js ESM transformation, or transpile your code to CommonJS before runtime if `node-hook` is essential for a specific part of your application.

affects: >=0.1.0

gotchaThe project appears to be abandoned, with its last release in 2017. This means it receives no updates, bug fixes, or security patches. It may not work with newer Node.js versions or dependencies, and could pose a security risk due to unaddressed vulnerabilities.

fix

Evaluate whether an active, maintained alternative can fulfill the required functionality. If `node-hook` is critical, consider forking and maintaining it yourself, or thoroughly vetting it for compatibility and security in your specific environment.

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Attempting to use `import hook from 'node-hook';` in a CommonJS context or a file without `'type': 'module'` in `package.json`.

fix

Use the CommonJS `require` syntax: `const hook = require('node-hook');`

TypeError: Cannot read properties of undefined (reading 'hook') at Object.<anonymous> (test.js:3:16)

Incorrectly trying to call `require('node-hook').hook()` as a function, or attempting to access `hook` before it's properly assigned from the module's export.

fix

Access the `hook` function as a property: `const { hook } = require('node-hook');` or `const nodeHook = require('node-hook'); nodeHook.hook(...);`

My transform function isn't being applied to subsequent `require()` calls for the same file.

Node.js caches modules after their initial `require()` call. Subsequent `require()` calls for the same file return the cached version without re-running transforms.

fix

To ensure your transform is applied, clear the module from the `require.cache` before re-requiring: `delete require.cache[require.resolve('./your-module')];`

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/bahmutov/node-hook ↗

packagehttps://www.npmjs.com/package/node-hook ↗