tracepack

Tracepack

Tracepack is a dependency investigator for modern npm projects.

It helps answer the questions that come up in real repos:

• What is in this dependency graph?
• Why is this package present?
• What pulled it in?
• Where are duplicate versions hiding?

Tracepack is not trying to be a generic graph generator or a browser UI. The goal for v0.1.0 is a fast, maintainable, npm-first tool that produces practical output for terminals, scripts, and CI.

Why Tracepack Exists

The JavaScript tooling ecosystem already has graphing tools, and npm itself can explain parts of the installed tree. Tracepack exists because day-to-day dependency debugging often needs a tighter loop:

• deterministic lockfile inspection when possible
• a clean fallback to the installed tree or declared dependencies
• reverse tracing that is easy to read
• duplicate-version surfacing that is useful in CI
• output that stays stable enough to script against

In short: Tracepack is built for investigation, not just visualization.

What Makes It Different

Tracepack deliberately focuses on a narrower, more opinionated slice of the problem:

• npm-first, with lockfile-first source selection
• reverse path tracing as a first-class capability
• duplicate-version reporting as a practical investigation and CI feature
• one normalized graph model shared by the library API, CLI, and renderers
• plain output that degrades gracefully in large repos

It does not try to support every package manager, every policy engine, or every visualization mode in v0.1.0.

Install

npm install --save-dev tracepack

Or run it directly:

npx tracepack

CLI Usage

tracepack [options]

Core options:

• --json output stable JSON
• --dot output Graphviz DOT
• --focus <pkg> show the forward subgraph starting at a package
• --reverse <pkg> explain why a package is present
• --max-depth <n> limit rendered depth
• --omit <dev|peer|optional> omit dependency edge types
• --source <auto|lockfile|installed|manifest> choose the npm data source
• --duplicates report duplicate versions
• --check-duplicates exit with code 2 when duplicates are found
• --cwd <path> inspect another project directory
• --help
• --version

Examples:

tracepack
tracepack --json
tracepack --dot
tracepack --focus react
tracepack --reverse esbuild
tracepack --max-depth 3
tracepack --omit dev
tracepack --duplicates
tracepack --check-duplicates

Input Modes

Tracepack supports three npm-first input modes:

• lockfile: parse package-lock.json v2/v3 for deterministic graphs
• installed: inspect the actual installed tree through Arborist
• manifest: inspect declared dependencies from package.json files and npm workspaces

Default source selection is:

• package-lock.json
• node_modules
• package.json

Output Examples

Default ASCII output:

Tracepack graph (lockfile)

app@1.0.0 [root]
├─ react@18.3.1
│  └─ loose-envify@1.4.0
│     └─ js-tokens@4.0.0
└─ vite@5.4.2

Duplicate versions
- postcss: 8.4.31, 8.4.35

Reverse tracing:

Tracepack reverse view for "esbuild" (lockfile)

app@1.0.0 [root]
└─ vite@5.4.2
   └─ esbuild@0.21.5

DOT output is designed to work cleanly with Graphviz and other tooling:

tracepack --dot > graph.dot
dot -Tsvg graph.dot -o graph.svg

Library API

import {
  buildGraph,
  findDuplicates,
  findReversePaths,
  toAscii,
  toDot,
  toJson
} from "tracepack";

const graph = await buildGraph({
  cwd: process.cwd(),
  source: "auto"
});

console.log(toAscii(graph, { reverse: "esbuild" }));
console.log(findDuplicates(graph));
console.log(findReversePaths(graph, "react"));
console.log(toJson(graph));
console.log(toDot(graph));

Public API:

• buildGraph(options)
• findDuplicates(graph)
• findReversePaths(graph, packageName, options?)
• toAscii(graph, options?)
• toJson(graph, options?)
• toDot(graph, options?)

CI and Scripting

Tracepack is designed to be useful outside interactive terminals.

• JSON output is stable and deterministic
• --check-duplicates returns exit code 2 when duplicate versions are found
• plain text output avoids terminal-only formatting assumptions

Example:

tracepack --check-duplicates
tracepack --json > tracepack-report.json

Architecture

Tracepack keeps a clear separation between:

• resolvers that discover npm data
• core graph and investigation logic
• renderers that format a filtered view
• a thin CLI adapter over the library

See docs/architecture.md for the short architectural notes.

Roadmap

Planned follow-up work includes:

• per-workspace filtering in aggregated workspace repos
• a dedicated explain-style CLI mode
• optional CI failure for cycle detection
• lockfile diffing between revisions
• richer duplicate reports with hoist and location context
• package include and exclude filters
• pnpm backend after npm behavior is solid
• Yarn backend after npm behavior is solid

Non-Goals for v0.1.0

• browser UI
• interactive web visualization
• support for every package manager
• vulnerability database integration
• license compliance auditing
• a large configuration surface

Development

npm install
npm run lint
npm run typecheck
npm test
npm run build

The release checklist for the initial version lives in docs/release-plan-v0.1.0.md.

Contributing

Contributions are welcome, especially around npm graph correctness, reverse tracing, duplicate detection, and documentation quality.

Please read:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md