{"id":14807,"library":"perf_hooks","title":"Node.js `perf_hooks` Core Module (npm `perf_hooks` placeholder)","description":"The `perf_hooks` module is a fundamental, built-in Node.js core module that provides performance measurement APIs based on the W3C User Timing and Performance Timeline specifications. It enables developers to instrument and observe Node.js application behavior with high-resolution timers, performance marks, measures, and observers. Key APIs include `performance.now()`, `performance.mark()`, `performance.measure()`, `PerformanceObserver`, and `eventLoopUtilization()` for monitoring event loop delays. This functionality is part of Node.js itself and does not require a separate npm installation; it is stable across all supported Node.js versions (currently 18.x LTS, 20.x LTS, 22.x LTS, with new versions released regularly). Critically, the npm package `perf_hooks` (version 0.0.1) mentioned in the metadata is a long-abandoned placeholder, last published nine years ago. Despite having high weekly downloads, it offers no actual functionality and should *never* be installed or used. Users seeking performance tooling should rely exclusively on the `node:perf_hooks` core module.","status":"abandoned","version":"0.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/mcollina/perf_hooks","tags":["javascript"],"install":[{"cmd":"npm install perf_hooks","lang":"bash","label":"npm"},{"cmd":"yarn add perf_hooks","lang":"bash","label":"yarn"},{"cmd":"pnpm add perf_hooks","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { performance } from 'perf_hooks';","symbol":"performance","correct":"import { performance } from 'node:perf_hooks';"},{"note":"When using CommonJS, explicitly specify `node:` to ensure the core module is loaded. Omitting it risks loading the npm placeholder, which lacks this symbol.","wrong":"const { PerformanceObserver } = require('perf_hooks');","symbol":"PerformanceObserver","correct":"const { PerformanceObserver } = require('node:perf_hooks');"},{"note":"`timerify` is a Node.js-specific extension for measuring function execution time. It is only available via the core `node:perf_hooks` module.","wrong":"const { timerify } = require('perf_hooks'); // Incorrect for placeholder","symbol":"timerify","correct":"import { timerify } from 'node:perf_hooks';"}],"quickstart":{"code":"import { performance, PerformanceObserver } from 'node:perf_hooks';\n\n// Create a PerformanceObserver to collect and report performance entries.\nconst obs = new PerformanceObserver((list) => {\n  const entries = list.getEntries();\n  entries.forEach((entry) => {\n    console.log(`Entry: ${entry.name}, Type: ${entry.entryType}, Duration: ${entry.duration.toFixed(2)}ms`);\n  });\n  // Clear marks and measures after processing if they are no longer needed\n  performance.clearMarks();\n  performance.clearMeasures();\n});\n\n// Start observing 'mark' and 'measure' events.\nobs.observe({ entryTypes: ['mark', 'measure'] });\n\n// Simulate an asynchronous operation with performance marks.\nasync function simulateWork() {\n  performance.mark('startWork');\n  await new Promise(resolve => setTimeout(resolve, Math.random() * 500)); // Simulate async task\n  performance.mark('endWork');\n  performance.measure('Total Work Time', 'startWork', 'endWork');\n\n  performance.mark('startAnotherTask');\n  let sum = 0;\n  for (let i = 0; i < 1_000_000; i++) {\n    sum += i; // CPU-bound task\n  }\n  performance.mark('endAnotherTask');\n  performance.measure('CPU Bound Task', 'startAnotherTask', 'endAnotherTask');\n  console.log('Simulated work complete. Sum:', sum);\n}\n\nsimulateWork();\n\n// Example of Event Loop Utilization\nimport { eventLoopUtilization } from 'node:perf_hooks';\n\nconst eluBefore = eventLoopUtilization();\nsetTimeout(() => {\n  const eluAfter = eventLoopUtilization(eluBefore);\n  console.log(`Event Loop Utilization: ${eluAfter.utilization.toFixed(4)}`);\n}, 1000);","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=0.0.1"},{"fix":"Always explicitly use `require('node:perf_hooks')` or `import 'node:perf_hooks'` to guarantee you are loading the built-in Node.js module.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1 (npm package); All Node.js versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All Node.js versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: (0 , perf_hooks_1.performance) is not a function"},{"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.","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).","error":"Error: Cannot find module 'perf_hooks'"}],"ecosystem":"npm"}