![Logo](./packages/node-modules-inspector/src/public/favicon.svg)

# Node Modules Inspector

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![bundle][bundle-src]][bundle-href]
[![JSDocs][jsdocs-src]][jsdocs-href]
[![License][license-src]][license-href]

Visualize your node_modules, inspect dependencies, and more.

## Quick Start

Try it by running following command under your `pnpm`/`npm`/`bun` project.

```bash
pnpx node-modules-inspector
```
```bash
npx node-modules-inspector
```
```bash
bunx node-modules-inspector
```

> Currently supports `pnpm`, `npm`, and `bun` projects. We are counting on the community to bring support for other package managers.

### Online Version

You can also try an online version at [**node-modules.dev**](https://node-modules.dev/), powered by [WebContainer](https://webcontainers.io/).

## Configuration

You can create a `node-modules-inspector.config.ts` file in your project root to configure the inspector's default behaviour.

```js
import { defineConfig } from 'node-modules-inspector'

export default defineConfig({
  defaultFilters: {
    excludes: [
      'eslint',
    ],
  },
  defaultSettings: {
    moduleTypeSimple: true,
  },

  // Experimental publint.dev integration, default is false
  publint: true

  // ...see jsdoc for more options and details
})
```

## Static Build

You can also build a static SPA of your current node_modules status:

```bash
pnpx node-modules-inspector build
```
```bash
npx node-modules-inspector build
```
```bash
bunx node-modules-inspector build
```

Then you can host the `.node-modules-inspector` folder with any static file server.

You can see a build for all Anthony Fu's packages at [everything.antfu.dev](https://everything.antfu.dev).

## CLI Reports

In addition to the web UI, the inspector exposes three machine-readable reports designed for shell pipelines and AI coding agents:

```bash
npx node-modules-inspector report duplicates   # packages installed in multiple versions
npx node-modules-inspector report sizes        # packages sorted by install size
npx node-modules-inspector report maintainers  # dep-upgrade opportunities + publint, grouped by consumer/author
```

Each command renders a pretty ANSI table by default. Add `--json` to emit JSON to stdout — progress logs go to stderr, so output is pipe-safe:

```bash
npx node-modules-inspector report duplicates --json | jq '.[].name'
npx node-modules-inspector report sizes --json --limit 10
npx node-modules-inspector report maintainers --json --sort migration --no-latest-only
```

Common options across all reports: `--root <dir>`, `--config <file>`, `--depth <n>`, `--limit <n>`. Run `node-modules-inspector report --help` for the full per-report flag set.

## MCP Server

The same three reports are exposed as MCP tools for AI coding agents. Start the server over stdio:

```bash
npx node-modules-inspector mcp
```

Tools exposed:
- `nmi:report-duplicates`
- `nmi:report-sizes`
- `nmi:report-maintainers`

Input/output JSON Schemas are auto-derived from the underlying valibot definitions and surfaced via `tools/list`. Wire it into Claude Code (or any MCP-compatible client) by adding `node-modules-inspector mcp` as a stdio server in your MCP config.

> [!NOTE]
> An [agent skill](./skills/node-modules-inspector/SKILL.md) lives at `skills/node-modules-inspector/SKILL.md` (repo root) and is copied into the published tarball at `<pkg>/skills/` during `prepack`. If your project uses [`skills-npm`](https://github.com/antfu/skills-npm), the skill is automatically symlinked into your agent's skill directory after `pnpm install`.

## Screenshots

![Image](https://github.com/user-attachments/assets/80ce6f9d-26fb-4fcf-8c51-e3d2b6f9f24c)
![Image](https://github.com/user-attachments/assets/6de8614c-2663-4c69-bd1e-96e8e66673a7)
![Image](https://github.com/user-attachments/assets/b3efa459-6a6a-41c4-a9cd-5afac9268bf8)

## Credits

- This project is heavily inspired by [npmgraph](https://npmgraph.js.org/)
- Thanks to [@wooorm](https://github.com/wooorm) for the module type detection algorithm in [wooorm/npm-esm-vs-cjs](https://github.com/wooorm/npm-esm-vs-cjs)
- The logo is derivated from the `black-hole-line-duotone` icon (yeah it's a black hole!) from the [Solar Icon Sets](https://www.figma.com/community/file/1166831539721848736/solar-icons-set) by [480 Design](https://www.figma.com/@480design) and [R4IN80W](https://www.figma.com/@voidrainbow) under the [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/) license.
- Thanks to [@privatenumber](https://github.com/privatenumber) for [pkg-size.dev](https://pkg-size.dev/) for running analysis with installations in WebContainer.

## Sponsors

<p align="center">
  <a href="https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg">
    <img src='https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg' alt='Sponsors' />
  </a>
</p>

## License

[MIT](./LICENSE) License © [Anthony Fu](https://github.com/antfu)

<!-- Badges -->

[npm-version-src]: https://img.shields.io/npm/v/node-modules-inspector?style=flat&colorA=080f12&colorB=1fa669
[npm-version-href]: https://npmjs.com/package/node-modules-inspector
[npm-downloads-src]: https://img.shields.io/npm/dm/node-modules-inspector?style=flat&colorA=080f12&colorB=1fa669
[npm-downloads-href]: https://npmjs.com/package/node-modules-inspector
[bundle-src]: https://img.shields.io/bundlephobia/minzip/node-modules-inspector?style=flat&colorA=080f12&colorB=1fa669&label=minzip
[bundle-href]: https://bundlephobia.com/result?p=node-modules-inspector
[license-src]: https://img.shields.io/github/license/antfu/node-modules-inspector.svg?style=flat&colorA=080f12&colorB=1fa669
[license-href]: https://github.com/antfu/node-modules-inspector/blob/main/LICENSE
[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
[jsdocs-href]: https://www.jsdocs.io/package/node-modules-inspector