Node.js `perf_hooks` Core Module (npm `perf_hooks` placeholder)

Common errors

• TypeError: (0 , perf_hooks_1.performance) is not a function

  cause 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.
  fix Change 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'

  cause 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).
  fix If 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.

Warnings

• breaking The 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.
  Fix: Do 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`.
• gotcha Using `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.
  Fix: Always explicitly use `require('node:perf_hooks')` or `import 'node:perf_hooks'` to guarantee you are loading the built-in Node.js module.
• gotcha The `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.
  Fix: Be 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.

Install

• npm install perf_hooks npm
• yarn add perf_hooks yarn
• pnpm add perf_hooks pnpm

Imports

• performance
  wrong:

  import { performance } from 'perf_hooks';

  correct:

  import { performance } from 'node: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
  wrong:

  const { PerformanceObserver } = require('perf_hooks');

  correct:

  const { PerformanceObserver } = require('node: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
  wrong:

  const { timerify } = require('perf_hooks'); // Incorrect for placeholder

  correct:

  import { timerify } from 'node:perf_hooks';

  `timerify` is a Node.js-specific extension for measuring function execution time. It is only available via the core `node:perf_hooks` module.

Quickstart

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