{"id":15330,"library":"get-caller-file","title":"Get Caller File Path","description":"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.","status":"active","version":"2.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/stefanpenner/get-caller-file","tags":["javascript"],"install":[{"cmd":"npm install get-caller-file","lang":"bash","label":"npm"},{"cmd":"yarn add get-caller-file","lang":"bash","label":"yarn"},{"cmd":"pnpm add get-caller-file","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import getCallerFile from 'get-caller-file';\n// OR\nimport { getCallerFile } from 'get-caller-file';","symbol":"getCallerFile","correct":"const getCallerFile = require('get-caller-file');"}],"quickstart":{"code":"// my-library-entry.js\nconst getCallerFile = require('get-caller-file');\n\n// A function typically exposed by a library\nfunction simulateLibraryCall(position = 2) {\n  // We want to find who called 'simulateLibraryCall'.\n  // position = 2 gives us the direct caller's file (e.g., index.js).\n  // position = 1 would be 'my-library-entry.js' itself.\n  return getCallerFile(position);\n}\n\nmodule.exports = simulateLibraryCall;\n\n// --- In a separate file, e.g., index.js ---\n// Simulate a user's application file calling into our library\nconst libraryFunction = require('./my-library-entry.js');\n\nfunction applicationLogic() {\n  const callerFile = libraryFunction();\n  console.log(`The file that called 'libraryFunction' is: ${callerFile}`);\n  // Expected output (will vary by system path): The file that called 'libraryFunction' is: /full/path/to/this/file/index.js\n  return callerFile;\n}\n\napplicationLogic();\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Use the CommonJS `require` syntax: `const getCallerFile = require('get-caller-file');`.","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.","error":"TypeError: getCallerFile is not a function"},{"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.","cause":"Attempting to use `require()` in an ES module (ESM) context without proper CJS interop or a bundler.","error":"ReferenceError: require is not defined"},{"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.","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.","error":"Returns `undefined` or throws an error when run in a browser or non-Node environment."}],"ecosystem":"npm"}