Node.js Require Hook

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause 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)

  cause 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.

  cause 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')];`

Warnings

• breaking Version 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.
• gotcha Node.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')]`.
• breaking node-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.
• gotcha The 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.

Install

• npm install node-hook npm
• yarn add node-hook yarn
• pnpm add node-hook pnpm

Imports

• hook
  wrong:

  import hook from 'node-hook';

  correct:

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

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

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

  correct:

  const { hook } = require('node-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.

Quickstart

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);