Dependency Cruiser

Common errors

• Error: Cannot find module 'typescript'

  cause Attempting to analyze a TypeScript project without `typescript` installed as a dependency or globally.
  fix Install TypeScript: `npm install --save-dev typescript` (local) or `npm install -g typescript` (global).

• Error: Unknown output type 'svg' (or 'png', 'jpg')

  cause Using an output type directly (like `svg`) that `dependency-cruiser` doesn't generate natively; these formats require an external tool like `Graphviz`.
  fix Use `--output-type dot` with `dependency-cruiser` and then pipe the output to the `dot` command from Graphviz: `npx depcruise src --output-type dot | dot -T svg > output.svg`.

• ERROR: [no-circular] (dependency-graph.js) → main.js

  cause A circular dependency was detected in your codebase, violating a rule configured in `.dependency-cruiser.js`.
  fix Refactor your modules to break the circular dependency. This often involves applying dependency inversion principles, extracting shared logic to a common module, or re-evaluating module responsibilities.

• TypeError: (0, dependency_cruiser_1.cruise) is not a function

  cause Attempting to use `dependency-cruiser`'s programmatic API with CommonJS `require` syntax or without properly awaiting the `cruise` function after upgrading to v13+.
  fix For v13+, the API is ESM-only and asynchronous. Change your import to `import { cruise } from 'dependency-cruiser';` and ensure you `await cruise(...)` within an `async` function.

Warnings

• breaking Starting with v13, the `--config` CLI option is no longer necessary and is ignored if a `.dependency-cruiser.js` file is found in the current directory or a parent. If you explicitly passed `--config` in v12 or older, you can remove it. For programmatic API users, v13 introduced several breaking changes including an ESM-only API, asynchronous `cruise` function, and a changed `cruise` signature.
  Fix: Remove the `--config` option from CLI commands. For API users, refactor `require` statements to `import` and update the `cruise` function call to `await cruise(...)` ensuring it handles promises and the updated signature. Ensure your Node.js version is compatible with v13+ (Node 14 support was dropped).
• gotcha When using `pnpx` (from pnpm) instead of `npx`, be aware that `pnpx` has different semantics which might affect how commands are executed or how packages are resolved. The documentation advises caution when mixing package managers.
  Fix: Prefer `npx` for executing `dependency-cruiser` commands unless you are fully aware of `pnpx`'s behavior and potential differences, especially regarding package resolution and environment setup.
• gotcha Generating visual output formats like SVG from the `.dot` format requires the external `Graphviz` tool to be installed on your system. `dependency-cruiser` itself outputs `.dot` files, which then need to be piped to the `dot` command.
  Fix: Install Graphviz on your system. For most Linux-like systems, this can be done via your package manager (e.g., `sudo apt-get install graphviz`). Refer to the Graphviz download page for other operating systems.
• gotcha The `picomatch` library, an internal dependency, had a reported vulnerability that was deemed 'irrelevant for dependency-cruiser's context' in a recent release. However, this might still trigger false positives in automated security scanners.
  Fix: No direct fix is required for `dependency-cruiser`'s functionality, as the vulnerability is contextually irrelevant. If security scanners flag it, you may need to add an override in your `package.json` to a later `picomatch` version or document the false positive.
• gotcha For TypeScript projects, if you observe that dependencies within TypeScript files (especially pre-compilation ones) are not correctly analyzed or found, it might be due to `dependency-cruiser` not finding the TypeScript compiler. It uses the transpiler already in your project or globally.
  Fix: Ensure `typescript` is installed as a `devDependency` in your project or globally in a location accessible to `dependency-cruiser`. You might also need to set `tsPreCompilationDeps: true` in your configuration for a more complete analysis of TypeScript-specific dependencies.

Install

• npm install dependency-cruiser npm
• yarn add dependency-cruiser yarn
• pnpm add dependency-cruiser pnpm

Imports

• cruise
  wrong:

  const cruise = require('dependency-cruiser');

  correct:

  import { cruise } from 'dependency-cruiser';

  Since v13, the API is ESM-only and asynchronous. While CJS might work in some contexts, ESM is the officially supported and recommended way for programmatic use.
• format
  wrong:

  import format from 'dependency-cruiser/format';

  correct:

  import { format } from 'dependency-cruiser';

  The `format` function, used to transform raw cruise results into various output formats, is a named export from the main package.
• IConfiguration
  wrong:

  import { IConfiguration } from 'dependency-cruiser';

  correct:

  import type { IConfiguration } from 'dependency-cruiser';

  Used for type-checking configuration objects, typically within a `.dependency-cruiser.js` file with a JSDoc comment like `/** @type {import('dependency-cruiser').IConfiguration} */`. Should be imported as a type.

Quickstart

Installs Dependency Cruiser, generates a basic configuration, then demonstrates CLI usage for visual graph generation and programmatic API usage for rule validation in a TypeScript project.

npm install --save-dev dependency-cruiser
npx depcruise --init
# Answer prompts to generate .dependency-cruiser.js configuration

# Run analysis and generate an SVG graph using Graphviz dot tool
npx depcruise src --include-only "^src" --output-type dot | dot -T svg > dependency-graph.svg

# For programmatic use, e.g., in a CI/CD pipeline or custom script:
// my-analysis.ts
import { cruise, format } from 'dependency-cruiser';
import type { IConfiguration, ICruiseResult } from 'dependency-cruiser';

const config: IConfiguration = {
  forbidden: [
    {
      name: 'no-circular',
      comment: 'This dependency is part of a circular relationship.',
      severity: 'warn',
      from: {}, to: { circular: true }
    },
    {
      name: 'no-internal-to-external',
      comment: 'Don\'t allow internal code to depend on external libraries outside of an adapter layer.',
      severity: 'error',
      from: { path: '^src/(?!adapters)' },
      to: { dependencyTypes: ['npm', 'npm-dev'] }
    }
  ],
  options: {
    // Configure to resolve TypeScript paths, etc.
    tsPreCompilationDeps: true,
    doNotFollow: {
      path: 'node_modules'
    },
    moduleSystems: ['es6', 'cjs'],
  }
};

async function analyzeDependencies() {
  try {
    const { output, exitCode } = await cruise(
      ['src'], // Files or globs to cruise
      config
    ) as ICruiseResult;

    if (exitCode !== 0) {
      console.error('Dependency violations found:\n', output);
    } else {
      console.log('No dependency violations found.');
    }

    // Example of using format for custom reporting (e.g., HTML)
    // const htmlReport = format(output, { outputType: 'html' });
    // console.log(htmlReport);

  } catch (error: any) {
    console.error('Error during dependency cruising:', error.message);
    process.exit(1);
  }
}

analyzeDependencies();