rollup-plugin-import-trace

1.0.1 verified Mon Apr 27 auth: no javascript

Rollup/Vite plugin that attaches a detailed import trace chain to build errors, helping developers quickly identify which import path led to a problematic file. Version 1.0.1 is the current stable release. It works with Rollup 3/4 and Vite 5/6/7. Unlike Rollup's built-in `watchFiles` (which lists all watched files), this plugin records only the specific chain of imports causing the error. Ships TypeScript types and supports both ESM and CommonJS environments. Minimal configuration required: just add `importTrace()` first in the plugins array.

Common errors

error Error: 'importTrace' is not exported from 'rollup-plugin-import-trace' ↓

cause Using CommonJS `require` with named export incorrectly

fix

Use const { importTrace } = require('rollup-plugin-import-trace') or switch to ESM import.

error TypeError: Cannot read properties of undefined (reading 'id') ↓

cause Plugin was not added to the plugins array, or was added after other plugins that override `resolveId` hook.

fix

Ensure importTrace() is the first plugin in the plugins array.

Warnings

gotcha Plugin must be listed first in the plugins array to capture import relationships. ↓

fix Place `importTrace()` before any other plugins in the Rollup or Vite configuration.

gotcha In Vite dev mode, error formatting is automatic; in other contexts you must manually call `patchErrorWithTrace()`. ↓

fix Use `patchErrorWithTrace(error)` before logging the error message for CLI tools or custom error handling.

gotcha Import trace may not be present for all error types; relies on Rollup's error structure and may miss runtime errors. ↓

fix Check `error.importTrace` existence before using it, or rely on `patchErrorWithTrace()` which handles absence gracefully.

Install

npm install rollup-plugin-import-trace

yarn add rollup-plugin-import-trace

pnpm add rollup-plugin-import-trace

Imports

importTrace
wrong
```
const importTrace = require('rollup-plugin-import-trace').importTrace
```
correct
```
import { importTrace } from 'rollup-plugin-import-trace'
```
Library is ESM-first but also exports a CJS default; named import works in both systems. Ensure your bundler resolves correctly.
default
wrong
```
const importTrace = require('rollup-plugin-import-trace')
```
correct
```
import importTrace from 'rollup-plugin-import-trace'
```
Default export is an alias for the named export. In CJS, use `{ importTrace }` or `require('rollup-plugin-import-trace').default`.

patchErrorWithTrace

wrong

const patchErrorWithTrace = require('rollup-plugin-import-trace').patchErrorWithTrace

correct

import { patchErrorWithTrace } from 'rollup-plugin-import-trace'

Utility function to format and append import trace to error messages. Accepts `unknown` type, no-op if trace missing.

Quickstart

Demonstrates basic usage of importTrace plugin with Rollup, catching an error and inspecting the importTrace property.

import { importTrace } from 'rollup-plugin-import-trace';
import { rollup } from 'rollup';

const bundle = await rollup({
  input: 'src/index.js',
  plugins: [importTrace()]
});

try {
  await bundle.generate({ format: 'es' });
} catch (error) {
  console.log(error.importTrace); // outputs import chain or undefined
}