Callsites

4.2.0 · active · verified Tue Apr 21

Callsites is a low-level utility that retrieves an array of V8 CallSite objects from the current JavaScript stack trace. It provides direct access to the V8 stack trace API, allowing developers to inspect intricate details of each call in the stack, such as file names, line numbers, column numbers, function names, and execution context. This package is currently stable at version 4.2.0 and maintains an active release cadence, with recent updates adding Bun support and refining TypeScript definitions. It is a pure ESM package since v4.0.0, making it suitable for modern Node.js environments. Its primary differentiator is providing raw, unopinionated access to V8's callsite information, empowering advanced debugging, logging, and error reporting scenarios.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/callsites/index.js from /path/to/your/file.js not supported.
```
cause Attempting to `require('callsites')` in a CommonJS module after `callsites` upgraded to pure ESM in v4.0.0.

fix Either convert your project or the specific file to an ES Module (by adding `"type": "module"` to your `package.json` or changing the file extension to `.mjs`), or use dynamic `import()`: `const callsites = await import('callsites');`
```
TypeError: callsites is not a function
```
cause This error can occur if you are in a CJS module and tried `const callsites = require('callsites').default;` or if the module resolution incorrectly imported something other than the default export.

fix Since v4.0.0, `callsites` is pure ESM and should be imported using `import callsites from 'callsites';`. If you *must* use CommonJS, use dynamic import: `const callsitesPromise = import('callsites'); callsitesPromise.then(mod => mod.default());`
```
TypeError: callsite.getFileName is not a function
```
cause Attempting to call a `get*` method on an object that is not a V8 `CallSite` instance, or trying to access a property directly like `callsite.fileName` instead of calling the method.

fix Ensure the object you're interacting with is indeed a `CallSite` instance from the `callsites()` array, and always use the method syntax, e.g., `callsite.getFileName()`.

Warnings

breaking Version 4.0.0 converted `callsites` to a pure ES Module (ESM). This means it can no longer be `require()`-d in CommonJS (CJS) contexts. Existing CJS projects must migrate to ESM or use an older version.
Fix: Migrate your project to use ES Modules (`type: "module"` in `package.json` or `.mjs` files), or dynamically import `callsites` using `import()` if you must remain in CJS. For example: `const callsites = await import('callsites');`
breaking Version 4.0.0 raised the minimum Node.js requirement to 12.20. Projects running on older Node.js versions will need to upgrade their runtime.
Fix: Ensure your Node.js environment is version 12.20 or newer. You can use tools like `nvm` or Docker to manage Node.js versions.
gotcha CallSite objects returned by `callsites()` are not plain JavaScript objects. They expose methods (e.g., `getFileName()`, `getLineNumber()`) to access stack trace information, rather than direct properties.
Fix: Always use the provided `get*` methods on the `CallSite` objects (e.g., `callsite.getFileName()`) instead of trying to access properties directly (e.g., `callsite.fileName`). Refer to the V8 Stack Trace API documentation for available methods.
gotcha The `getFunctionName()` and `getMethodName()` methods attempt to infer names, which can sometimes be unreliable or return `null` or empty strings, especially with anonymous functions, minified code, or complex execution contexts.
Fix: Do not solely rely on function name inference for critical logic. Combine with other identifiers like `getFileName()` and `getLineNumber()` for more robust stack analysis. Consider providing named functions where possible.

Install

npm install callsites npm
yarn add callsites yarn
pnpm add callsites pnpm

Imports

callsites
wrong:
```
const callsites = require('callsites');
```
correct:
```
import callsites from 'callsites';
```
The package is pure ESM since v4.0.0. CommonJS `require()` is not supported.
CallSite
wrong:
```
import { CallSite } from 'callsites';
```
correct:
```
import type { CallSite } from 'callsites';
```
Use `import type` for the TypeScript `CallSite` interface to avoid bundling issues and indicate it's a type-only import. The `CallSite` object itself is returned by the default export.
callsites() in async functions
```
async function myAsyncFunc() {
  const stack = callsites();
  const asyncCallsite = stack.find(c => c.isAsync());
  // ...
}
```
While `callsites()` itself is synchronous, the returned `CallSite` objects gained new methods like `isAsync()`, `isPromiseAll()`, and `getPromiseIndex()` in v4.2.0 to correctly identify and inspect asynchronous calls within the stack trace.

Quickstart

Demonstrates how to use `callsites` to retrieve the filename of the function that called the immediate parent function in the stack trace.

import callsites from 'callsites';

function getCallerFileName() {
  // callsites()[0] is the call to `callsites` itself
  // callsites()[1] is `getCallerFileName`
  // callsites()[2] is the function that called `getCallerFileName`
  const callerCallsite = callsites()[2];
  if (callerCallsite) {
    return callerCallsite.getFileName();
  }
  return 'Unknown file';
}

function myApplicationLogic() {
  const filename = getCallerFileName();
  console.log(`This function was called from: ${filename}`);
}

myApplicationLogic();
// Example output: This function was called from: /path/to/your/file.js

view raw JSON →