Node Modules Inspector

node-modules-inspector

node-modules-inspector is a CLI + MCP server that inspects the installed node_modules of the current project and produces structured reports. Three reports, same underlying analysis pipeline:

Reports run against the real on-disk node_modules — no registry calls are required for the basic shape; npm metadata is fetched only to enrich the maintainers report (gated by config).

Works with pnpm, npm, and bun. The default npx node-modules-inspector (with no subcommand) opens a Vue web UI for humans; agents should use the report and mcp subcommands below.

When to reach for this

Trigger on any of:

• "audit my dependencies", "find duplicate packages", "node_modules cleanup"
• "what's taking up disk space in node_modules"
• "which deps are outdated" / "what dep-upgrade opportunities are there"
• "show me publint issues across my deps"
• "who maintains my dependencies"

Don't reach for it for: registry-only questions (use fast-npm-meta), bundle-size analysis of a single package (use a bundler-specific tool), security audits (use npm audit / osv-scanner).

CLI mode

All subcommands share these options:

• --root <dir> — project root (default: cwd)
• --config <file> — config file (default: node-modules-inspector.config.{ts,js,json})
• --depth <n> — max dependency depth to traverse (default: 8)
• --json — emit JSON to stdout; pretty ANSI table otherwise

Progress logs always go to stderr, so ... --json is pipe-safe.

duplicates

npx node-modules-inspector report duplicates --json

Options:

• --min-versions <n> — only include packages installed at this many versions or more (default: 2)
• --limit <n> — cap result count

Output shape:

[
  {
    "name": "@typescript-eslint/scope-manager",
    "versions": ["8.56.1", "8.59.1", "8.59.2", "8.59.4"],
    "specs": ["@typescript-eslint/scope-manager@8.56.1", "..."]
  }
]

Versions are sorted ascending by semver. Entries are sorted by version-count descending. Use this to find dedupe targets — pnpm dedupe / npm dedupe resolves these where ranges overlap.

sizes

npx node-modules-inspector report sizes --json --limit 20

Options:

• --limit <n> — cap result count (default: 50)
• --include-workspace — include workspace packages (default: excluded; they have no meaningful install size)

Output shape:

[
  {
    "spec": "typescript@6.0.3",
    "name": "typescript",
    "version": "6.0.3",
    "workspace": false,
    "bytes": 24346827,
    "categories": {
      "js": { "bytes": 15344521, "count": 200 },
      "dts": { "bytes": 7002306, "count": 150 }
    }
  }
]

categories keys come from a fixed set: js, ts, dts, json, bin, wasm, map, image, css, html, comp, doc, test, flow, other. Entries are sorted by bytes descending.

maintainers

npx node-modules-inspector report maintainers --json

Options:

• --sort <depth|migration|latest> — sort by consumer depth, max migration ratio, or latest release time (default: depth)
• --author <handle> — filter to consumers maintained by this author; repeatable
• --no-publint — exclude publint findings
• --no-latest-only — include consumer packages that are not on their latest major
• --limit <n> — cap result count

Output shape:

[
  {
    "consumer": { "spec": "rollup-plugin-esbuild@6.2.1", "name": "rollup-plugin-esbuild", "version": "6.2.1", "depth": 1 },
    "authors": [{ "type": "github", "github": "egoist", "avatar": "..." }],
    "items": [
      {
        "kind": "dep-upgrade",
        "depName": "unplugin-utils",
        "depType": "prod",
        "declaredRange": "^0.2.4",
        "rawRange": "catalog:deps",
        "catalogName": "deps",
        "installedHighestVersion": "0.3.1",
        "installedHighestSpec": "unplugin-utils@0.3.1",
        "installedVersions": ["0.2.4", "0.3.1"],
        "migratedCount": 10,
        "totalCount": 11,
        "migrationRatio": 0.909
      },
      {
        "kind": "publint",
        "messages": [/* publint Message objects */],
        "counts": { "error": 0, "warning": 1, "suggestion": 2 }
      }
    ],
    "maxMigrationRatio": 0.909,
    "latestReleasedAt": 1739000000000
  }
]

How to read this:

• A dep-upgrade item means: this consumer declares depName at declaredRange, but there's a newer installed version (installedHighestVersion) that the range does not satisfy. migrationRatio is the fraction of consumers in the same cohort that already migrated — a high ratio (e.g. 0.9) means most other consumers already moved on, so this one is lagging.
• rawRange differs from declaredRange only when the consumer used a pnpm catalog reference (catalog:deps); declaredRange is the resolved range.
• A publint item carries the raw publint messages, partitioned by severity in counts.
• authors come from the consumer's package.json author/maintainers fields, with GitHub-handle detection.

Publint findings only appear when pkg.resolved.publint was populated. Enable that by adding publint: true to node-modules-inspector.config.ts (or by using the project's web UI which runs publint async).