deptrace

This one came from a tiny but persistent irritation in JavaScript projects.

Package managers can usually tell you why something is installed. Lockfiles can tell you how it got resolved. But when you're staring at a dependency and asking the actual practical question - "where the hell is this being used?" - the answer is often weirdly manual.

Search the package name. Miss a subpath import. Forget scripts. Miss config files. Ignore type-only imports. Remove the thing. Break the build.

I wanted a small tool that gave a calmer answer than that.

What It Does

deptrace is a Node CLI tool for explaining where a JavaScript or TypeScript dependency is actually used inside a selected project root.

You run:

npx @mxdhavgautam/deptrace <package-name> --cwd /path/to/project

and it gives you a report covering:

• the package declaration bucket in package.json
• installed package metadata from node_modules
• source imports, requires, re-exports, dynamic string imports, and type-only imports
• script usage, including installed package binary names
• config matches with confidence levels
• runtime signals like browser/client usage hints
• cautious verdicts like KEEP, REMOVE_CANDIDATE, MOVE_TO_DEV_CANDIDATE, REPLACE_OR_SHRINK, and INSPECT

It also has --json because a CLI like this should be usable by both humans and other tools.

The Important Bit

The thing I was careful about here was not pretending the tool knows more than it does.

Dependency cleanup can be dangerous if the tool gets overconfident. So deptrace is intentionally conservative. It does not claim to solve all unused dependency detection. It explains one dependency, in one selected JS/TS package root, using local evidence, and then gives a cautious next step.

The goal wasn't to get a simple "delete this" but instead "here is the evidence, now you make the next move".

That distinction matters.

The Engineering

The implementation is TypeScript, built as a lightweight Node CLI with Commander, Babel Parser, fast-glob, YAML, Vitest, and tsup.

The scanner normalizes package subpaths, handles scoped packages, classifies source/test/config/declaration files, parses AST import forms, scans scripts without dumb substring matching, checks config files, reads installed package metadata, and then feeds all of that into a verdict system.

The tests cover the annoying cases that usually make this kind of tool lie:

• scoped package subpaths
• type-only imports
• declaration files
• config imports
• script binary usage
• lockfile-only packages
• hoisted workspace installs
• duplicate declarations
• peer and optional dependencies
• dynamic or computed import forms that need diagnostics instead of false certainty

That last one is very much the spirit of the project. If the tool doesn't know, it should say so.

Why This Mattered to Me

This is a small CLI, but it reflects a kind of engineering taste I care about where you build the narrow thing, make the evidence visible, and avoid pretending automation is certainty.

deptrace is not trying to be a magic dependency janitor. It is trying to be the careful friend who points at the actual files before you delete something important.

I like tools like this. Small, boring in the right ways, and useful precisely because they reduce the amount of trust you have to place in vibes and can help you get actual references for actions you want to take.

The package is live and published on NPM, find it here: npmjs.com And the source code for it on my GitHub.