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.
performance
✓ import { performance } from 'node:perf_hooks';
✗ import { performance } from 'perf_hooks';
Always use the `node:` prefix for built-in Node.js modules to prevent accidental resolution to similarly named, often dysfunctional, npm packages. The bare 'perf_hooks' path might resolve to the abandoned npm placeholder.
PerformanceObserver
✓ const { PerformanceObserver } = require('node:perf_hooks');
✗ const { PerformanceObserver } = require('perf_hooks');
When using CommonJS, explicitly specify `node:` to ensure the core module is loaded. Omitting it risks loading the npm placeholder, which lacks this symbol.
timerify
✓ import { timerify } from 'node:perf_hooks';
✗ const { timerify } = require('perf_hooks'); // Incorrect for placeholder
`timerify` is a Node.js-specific extension for measuring function execution time. It is only available via the core `node:perf_hooks` module.
This quickstart demonstrates how to use `performance.mark()`, `performance.measure()`, and `PerformanceObserver` to track the duration of asynchronous and synchronous operations, as well as `eventLoopUtilization()` for Node.js performance monitoring.
import { performance, PerformanceObserver } from 'node:perf_hooks';
// Create a PerformanceObserver to collect and report performance entries.
const obs = new PerformanceObserver((list) => {
const entries = list.getEntries();
entries.forEach((entry) => {
console.log(`Entry: ${entry.name}, Type: ${entry.entryType}, Duration: ${entry.duration.toFixed(2)}ms`);
});
// Clear marks and measures after processing if they are no longer needed
performance.clearMarks();
performance.clearMeasures();
});
// Start observing 'mark' and 'measure' events.
obs.observe({ entryTypes: ['mark', 'measure'] });
// Simulate an asynchronous operation with performance marks.
async function simulateWork() {
performance.mark('startWork');
await new Promise(resolve => setTimeout(resolve, Math.random() * 500)); // Simulate async task
performance.mark('endWork');
performance.measure('Total Work Time', 'startWork', 'endWork');
performance.mark('startAnotherTask');
let sum = 0;
for (let i = 0; i < 1_000_000; i++) {
sum += i; // CPU-bound task
}
performance.mark('endAnotherTask');
performance.measure('CPU Bound Task', 'startAnotherTask', 'endAnotherTask');
console.log('Simulated work complete. Sum:', sum);
}
simulateWork();
// Example of Event Loop Utilization
import { eventLoopUtilization } from 'node:perf_hooks';
const eluBefore = eventLoopUtilization();
setTimeout(() => {
const eluAfter = eventLoopUtilization(eluBefore);
console.log(`Event Loop Utilization: ${eluAfter.utilization.toFixed(4)}`);
}, 1000);
Debug
Known issues
breakingThe npm package `perf_hooks` (version 0.0.1) is an abandoned placeholder and provides no functional APIs. Installing and attempting to use this package will result in runtime errors as its exports are empty or non-existent.fixDo NOT install `perf_hooks` from npm. The `perf_hooks` module is built directly into Node.js. Remove `perf_hooks` from your `package.json` and `node_modules`.
affects: >=0.0.1
gotchaUsing `require('perf_hooks')` or `import 'perf_hooks'` without the `node:` prefix can lead to confusion and potentially load the abandoned npm placeholder package instead of the core Node.js module, particularly in environments with complex module resolution or non-standard bundler configurations.fixAlways explicitly use `require('node:perf_hooks')` or `import 'node:perf_hooks'` to guarantee you are loading the built-in Node.js module. affects: >=0.0.1 (npm package); All Node.js versions
gotchaThe `perf_hooks` core module's global `performance` object is similar to `window.performance` in browsers but includes Node.js-specific extensions like `timerify()` and `eventLoopUtilization()` which are not available in web environments.fixBe mindful of platform differences when writing performance-related code intended for both browser and Node.js environments. Use Node.js-specific APIs only within Node.js.
affects: All Node.js versions
Errors
Common errors & fixes
TypeError: (0 , perf_hooks_1.performance) is not a function
Attempting to use `performance` from the abandoned `perf_hooks` npm package (version 0.0.1) which exports nothing, instead of the Node.js core module.
fixChange your import statement from `import { performance } from 'perf_hooks';` to `import { performance } from 'node:perf_hooks';` (or `require`). Ensure the npm package is uninstalled. Error: Cannot find module 'perf_hooks'
This error can occur if you've incorrectly removed the `perf_hooks` npm package but your code still tries to import it, or if you're trying to use `perf_hooks` in a non-Node.js environment (e.g., a browser without a polyfill/bundler setup).
fixIf running in Node.js, ensure you are importing from the core module using `node:perf_hooks`. If this error appears after uninstalling the npm package, it indicates a lingering reference. If running in a browser, `perf_hooks` is a Node.js-specific API and will not work without a compatibility layer or polyfill.
Audit
Dependencies
No dependency data recorded yet.