Node Modules Inspector

Common errors

• Error: Cannot find module 'node-modules-inspector/cli'

  cause Attempting to `require` or `import` a submodule path that does not exist or has been moved, or an incorrect import style for an ESM-first package. This often happens with CommonJS `require` calls.
  fix Ensure you are using correct ESM import paths (e.g., `import { run } from 'node-modules-inspector/cli';`) and that your project supports ESM. For direct CLI usage, prefer `npx node-modules-inspector`.

• TypeError: Cannot read properties of undefined (reading 'length') when accessing report data

  cause This typically occurs when trying to access properties of the analysis report object (e.g., `report.packages.length`) before the analysis is complete or if the property is unexpectedly `undefined` due to an error during analysis or an empty `node_modules` directory.
  fix Add checks for `report` and its properties being defined before accessing them. Ensure your project has a `node_modules` directory and dependencies are installed. Log the `report` object to inspect its structure if the issue persists.

• npx node-modules-inspector: command not found

  cause The `node-modules-inspector` package is not installed or `npx` cannot locate it in your environment. This might happen if npm's global bin path is not in your system's PATH, or if there's a temporary network issue preventing `npx` from downloading it.
  fix Ensure `npm` is correctly installed and its bin directory is in your system's PATH. You can also try installing the package globally first: `npm install -g node-modules-inspector`, then run `node-modules-inspector`.

Warnings

• gotcha The `node-modules-inspector` package is primarily designed as a CLI tool with an interactive UI. While it exposes a programmatic API, the most common and feature-rich way to use it is via `npx node-modules-inspector` in your project's root, which launches a local web-based interface for exploration.
  Fix: Prefer `npx node-modules-inspector` for interactive analysis. If integrating programmatically, refer to the package's source or examples for exact API details, as it may evolve.
• gotcha When using `node-modules-inspector` in CI/CD environments or for static reports, remember to use the `build` command (e.g., `npx node-modules-inspector build`). Simply running the inspector without the build command will not generate persistent output for later review or hosting.
  Fix: For non-interactive or deployable reports, run `npx node-modules-inspector build`. The output will be in a `.node-modules-inspector` folder which can then be served as static files.
• gotcha The tool relies on the structure and content of your `node_modules` directory. Issues with package manager caching, inconsistent installs, or corrupted `node_modules` can lead to incomplete or incorrect analysis reports.
  Fix: Ensure your `node_modules` is in a clean state by running `rm -rf node_modules && [your-package-manager] install` before using the inspector. This helps guarantee an accurate reflection of your project's dependencies.
• gotcha The 'vulnerability tab on report view' feature was added in v1.4.0. Users on older versions will not have access to this security analysis capability.
  Fix: Upgrade to `node-modules-inspector@latest` (or >=1.4.0) to benefit from the integrated vulnerability scanning in the report UI.

Install

• npm install node-modules-inspector npm
• yarn add node-modules-inspector yarn
• pnpm add node-modules-inspector pnpm

Imports

• run
  wrong:

  const run = require('node-modules-inspector/cli');

  correct:

  import { run } from 'node-modules-inspector/cli';
  // Or, for direct CLI usage:
  // npx node-modules-inspector

  The primary interaction is typically via `npx` or a script, but the `run` function allows programmatic execution of the CLI. The package is ESM-first, so direct CommonJS `require` is not recommended for core modules.
• analyzeProject
  wrong:

  import analyzeProject from 'node-modules-inspector/core'; // Incorrect default import

  correct:

  import { analyzeProject } from 'node-modules-inspector/core';
  // For detailed analysis.

  This symbol, or similar, is inferred for programmatic analysis based on the package's functionality. Named imports are standard for modern TypeScript/ESM libraries. Exact export name might vary, consult source if 'analyzeProject' fails.
• ModuleReport
  wrong:

  import { ModuleReport } from 'node-modules-inspector/types'; // Using `import` instead of `import type` for types.

  correct:

  import type { ModuleReport } from 'node-modules-inspector/types';

  When importing only types in TypeScript, `import type` is preferred for better tree-shaking and clarity, though `import` works at compile time. This type is for consuming the structured output of the analysis.

Quickstart

This quickstart demonstrates how to programmatically analyze a project's `node_modules` directory and log summary information.

import { analyzeProject } from 'node-modules-inspector/core';
import path from 'node:path';
import process from 'node:process';

async function inspectCurrentProject() {
  const projectPath = process.cwd();
  console.log(`Analyzing node_modules in: ${projectPath}\n`);

  try {
    // The `analyzeProject` function (inferred) would perform the core logic.
    // In a real scenario, this might return a structured report object.
    const report = await analyzeProject(projectPath, {
      // Optional: Specify package manager if not auto-detected
      packageManager: 'npm',
      // Optional: Include dev dependencies in the analysis
      includeDevDependencies: true,
      // Optional: Filter modules based on criteria
      filter: (module) => !module.name.startsWith('@types/'),
    });

    console.log('Analysis Complete! Key Insights:');
    console.log(`Total unique packages: ${report.packages.length}`);
    console.log(`Total disk size: ${report.totalSizeHumanReadable}`);
    console.log(`Duplicate packages found: ${report.duplicates.length}`);
    console.log(`Modules with known vulnerabilities: ${report.vulnerabilities?.length || 0}`);
    console.log('\nTo view the full interactive report, run:');
    console.log('npx node-modules-inspector');

  } catch (error) {
    console.error(`Error during analysis: ${error.message}`);
    console.error('Ensure you run this in a project with a node_modules directory.');
    console.error('If this error persists, try running `npx node-modules-inspector` directly.');
  }
}

inspectCurrentProject();