esbuild-plugin-fileloc

0.0.6 verified Mon Apr 27 auth: no javascript

An esbuild plugin that replaces __dirname, __filename, __line, __relativedirname, and __relativefilename with actual source file metadata at build time. Version 0.0.6, no release cadence documented. Unlike Node.js's __dirname (which resolves to the output file), this plugin provides the original source path, and the __line variable is unique among Node-like bundlers. Ships TypeScript declarations. Lightweight, no dependencies. Suitable for esbuild bundling projects that need source-level location globals.

Common errors

error Cannot find name '__dirname'. Do you need to change your target library? ↓

cause TypeScript does not know about the global variables without the type reference.

fix

Add /// <reference types="esbuild-plugin-fileloc" /> at the top of your file.

error Error: The plugin "esbuild-plugin-fileloc" is not a valid esbuild plugin. Expected either a string or an object with a name and setup function. ↓

cause The default export from the module is a function, not a plugin object. The user likely passed filelocPlugin (the function) instead of calling it.

fix

Change plugins: [filelocPlugin] to plugins: [filelocPlugin()].

error TypeError: filelocPlugin is not a function ↓

cause Importing with CommonJS require and destructuring the default export incorrectly.

fix

Use ESM import: import filelocPlugin from 'esbuild-plugin-fileloc'.

Warnings

gotcha Plugin must be called as a function: filelocPlugin() not filelocPlugin ↓

fix Use filelocPlugin() in the plugins array.

gotcha Global variables are only replaced in files processed by esbuild; they are not polyfilled at runtime ↓

fix Ensure all files that use these globals are bundled by esbuild with the plugin applied.

gotcha Type declarations require triple-slash reference; importing the module does not augment global scope ↓

fix Add /// <reference types="esbuild-plugin-fileloc" /> at the top of files that use the globals.

deprecated No known deprecations as of v0.0.6. ↓

fix N/A

Install

npm install esbuild-plugin-fileloc

yarn add esbuild-plugin-fileloc

pnpm add esbuild-plugin-fileloc

Imports

default export (plugin factory)
wrong
```
const { default: filelocPlugin } = require('esbuild-plugin-fileloc')
```
correct
```
import filelocPlugin from 'esbuild-plugin-fileloc'
```
ESM default import is the correct way. CJS require with destructuring of default fails because the package is ESM.
plugin in esbuild config
wrong
```
plugins: [filelocPlugin]
```
correct
```
import filelocPlugin from 'esbuild-plugin-fileloc';
esbuild.build({
  plugins: [filelocPlugin()],
})
```
The default export is a factory function that must be called (with no arguments) to create the plugin instance.
type reference
wrong
```
import 'esbuild-plugin-fileloc/types'
```
correct
```
/// <reference types="esbuild-plugin-fileloc" />
```
Types are declared as ambient globals via a triple-slash reference. Direct import of types is not supported.

Quickstart

Build a TypeScript file with esbuild and replace __dirname, __filename, __line, etc. with source location values.

import esbuild from 'esbuild';
import filelocPlugin from 'esbuild-plugin-fileloc';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  outfile: 'dist/bundle.js',
  bundle: true,
  plugins: [filelocPlugin()],
});