Get Caller File Path

2.0.5 · active · verified Tue Apr 21

get-caller-file is a specialized Node.js utility designed to programmatically determine the file path from which a given function was invoked. It achieves this by inspecting the V8 JavaScript engine's call stack at the point of invocation. The package is currently at version 2.0.5, with its development pace typically tied to the stability of V8's stack trace API, implying a generally stable but infrequent release cadence as the core functionality is mature. A key differentiator is its direct reliance on Node.js and V8-specific APIs, making it highly effective within its intended environment but explicitly unsuitable for other JavaScript runtimes like web browsers or non-V8 environments. This constraint is crucial for developers to note, as attempting to use it outside of Node.js will lead to unexpected behavior or errors. It serves a niche but critical role in scenarios requiring introspection into the call stack for debugging, logging, or module resolution purposes.

Common errors

```
TypeError: getCallerFile is not a function
```
cause Attempting to import `get-caller-file` using named or default ESM import syntax (e.g., `import getCallerFile from 'get-caller-file';` or `import { getCallerFile } from 'get-caller-file';`) when the package is a CommonJS module without explicit ESM exports.

fix Use the CommonJS `require` syntax: `const getCallerFile = require('get-caller-file');`.
```
ReferenceError: require is not defined
```
cause Attempting to use `require()` in an ES module (ESM) context without proper CJS interop or a bundler.

fix If in an ESM file, you can try `import getCallerFile = require('get-caller-file');` (TypeScript) or if pure JS, dynamically import it with `const { default: getCallerFile } = await import('get-caller-file');` (though `get-caller-file` is a function, not an object with a default property). The most reliable fix is often to ensure the consuming file is also CommonJS if using older Node.js versions, or use `createRequire` in Node.js ESM.
```
Returns `undefined` or throws an error when run in a browser or non-Node environment.
```
cause The package relies on V8-specific stack trace inspection and Node.js global objects that are not present in browser environments or alternative runtimes.

fix This package is strictly for Node.js. Do not include it in browser bundles or attempt to run it in non-Node.js environments. Use platform-specific code or provide a fallback for non-Node.js contexts.

Warnings

gotcha The package relies on Node.js and V8-specific stack trace APIs. It is not compatible with other JavaScript runtimes like web browsers, Deno, or other non-V8 environments. Attempting to use it outside of Node.js will result in errors or unexpected `undefined` return values.
Fix: Ensure the package is only used within a Node.js environment. Consider conditional imports or platform-specific logic if your codebase targets multiple runtimes.
gotcha Inspecting the V8 stack trace can have minor performance implications if called excessively in high-throughput loops. While generally negligible for typical usage, be mindful in performance-critical sections.
Fix: Profile your application if you suspect performance bottlenecks. Limit calls to `get-caller-file` in hot paths if performance becomes an issue. Cache results where appropriate.
gotcha The `position` argument (defaulting to 2) determines which stack frame's file name is returned. Misunderstanding this parameter can lead to retrieving the wrong file path (e.g., the file where `getCallerFile` is called, rather than its caller).
Fix: Carefully test and confirm the correct `position` value for your specific use case. `position = 1` refers to the file where `getCallerFile` itself is directly invoked, `position = 2` refers to its immediate caller, and so on.

Install

npm install get-caller-file npm
yarn add get-caller-file yarn
pnpm add get-caller-file pnpm

Imports

getCallerFile
wrong:
```
import getCallerFile from 'get-caller-file';
// OR
import { getCallerFile } from 'get-caller-file';
```
correct:
```
const getCallerFile = require('get-caller-file');
```
This package is primarily designed for CommonJS (`require`) in Node.js environments. Direct ESM import syntax for named or default exports is not natively supported for its current structure. Node.js ESM can `import` CJS modules via `import getCallerFile = require('get-caller-file')` (TypeScript) or dynamic `import('get-caller-file').then(m => m.default)` (JavaScript), but the simplest and most robust approach remains CommonJS `require` for full compatibility with older Node versions.

Quickstart

Demonstrates how to use `get-caller-file` to identify the file path of the function that initiated the call, simulating a common library usage pattern.

// my-library-entry.js
const getCallerFile = require('get-caller-file');

// A function typically exposed by a library
function simulateLibraryCall(position = 2) {
  // We want to find who called 'simulateLibraryCall'.
  // position = 2 gives us the direct caller's file (e.g., index.js).
  // position = 1 would be 'my-library-entry.js' itself.
  return getCallerFile(position);
}

module.exports = simulateLibraryCall;

// --- In a separate file, e.g., index.js ---
// Simulate a user's application file calling into our library
const libraryFunction = require('./my-library-entry.js');

function applicationLogic() {
  const callerFile = libraryFunction();
  console.log(`The file that called 'libraryFunction' is: ${callerFile}`);
  // Expected output (will vary by system path): The file that called 'libraryFunction' is: /full/path/to/this/file/index.js
  return callerFile;
}

applicationLogic();

view raw JSON →