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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
async_hooks (module import)
✓ import * as async_hooks from 'node:async_hooks';
✗ import * as async_hooks from 'async_hooks';
const async_hooks = require('async_hooks');
npm install async_hooks
This refers to the Node.js core module. The `node:` prefix is explicitly recommended to indicate a built-in module and prevent potential conflicts. Installing the npm package `async_hooks` is incorrect and will not provide the Node.js API.
AsyncLocalStorage
✓ import { AsyncLocalStorage } from 'node:async_hooks';
✗ import AsyncLocalStorage from 'node:async_hooks';
const { AsyncLocalStorage } = require('async_hooks');
npm install async_hooks
The recommended and stable API for asynchronous context tracking in Node.js, suitable for use cases like request ID propagation or tracing.
createHook
✓ import { createHook } from 'node:async_hooks';
✗ import createHook from 'node:async_hooks';
const { createHook } = require('async_hooks');
npm install async_hooks
This is part of the original, lower-level `async_hooks` API. Node.js documentation now discourages its use for new asynchronous context tracking, recommending `AsyncLocalStorage` instead due to usability, safety, and performance concerns.
Demonstrates `AsyncLocalStorage` for propagating a request ID across asynchronous operations in Node.js.
import { AsyncLocalStorage } from 'node:async_hooks';
const asyncLocalStorage = new AsyncLocalStorage();
function logWithId(message: string) {
const id = asyncLocalStorage.getStore()?.id ?? 'none';
console.log(`[Request ID: ${id}] ${message}`);
}
function handleRequest(requestId: string, callback: () => void) {
asyncLocalStorage.run({ id: requestId }, () => {
logWithId('Starting request processing');
// Simulate some asynchronous work
setTimeout(() => {
logWithId('Intermediate async step');
callback();
}, 100);
});
}
// Simulate incoming requests
console.log('--- Request 1 ---');
handleRequest('req-123', () => {
logWithId('Request 1 completed');
console.log('\n--- Request 2 ---');
handleRequest('req-456', () => {
logWithId('Request 2 completed');
console.log('\n--- Request 3 (no ID) ---');
logWithId('This will show no ID as it is not run within a store.');
});
});
Debug
Known issues
breakingDo NOT install the npm package `async_hooks`. It is a non-functional placeholder for a Node.js core module. Installing it will not provide the intended API and may lead to confusion or incorrect builds.fixRemove `async_hooks` from `package.json` and `node_modules`. Always import the core module directly using `import ... from 'node:async_hooks';` or `require('node:async_hooks');`. affects: >=1.0.0 (npm package)
deprecatedThe `createHook` and `AsyncHook` APIs are generally discouraged for new code in recent Node.js versions (v14+). They have known usability issues, safety risks, and performance implications.fixFor asynchronous context tracking, migrate to the `AsyncLocalStorage` API, which is stable and optimized.
affects: >=14.0.0 (Node.js)
gotchaCalling asynchronous operations like `console.log()` inside `async_hooks` callbacks (e.g., `init`, `before`, `after`, `destroy`) can cause infinite recursion, as these logging operations themselves trigger `async_hooks` events.fixFor debugging within `async_hooks` callbacks, use synchronous logging methods such as `fs.writeSync(1, msg)` to print to stdout without triggering further async events.
affects: >=8.0.0 (Node.js)
Errors
Common errors & fixes
Error: Cannot find module 'async_hooks'
Attempting to import `async_hooks` in an environment where it's not a core module (e.g., browser) or if Node.js cannot resolve the core module due to an incorrectly installed npm package of the same name.
fixEnsure you are running in a Node.js environment. If you have an `async_hooks` npm package installed, remove it. Use the explicit `node:` prefix for imports: `import * as async_hooks from 'node:async_hooks';`.
Error [ERR_REQUIRE_ESM]: require() of ES Module not supported.
Trying to use `require()` to import `node:async_hooks` (or any other ESM-only module) in a CommonJS module, or trying to `import` in a CommonJS file.
fixIf your project uses CommonJS, use `const async_hooks = require('node:async_hooks');`. If your project uses ES Modules, use `import * as async_hooks from 'node:async_hooks';`. Ensure your `package.json` `"type": "module"` is set correctly for ESM projects. Audit
Dependencies
No dependency data recorded yet.