{"id":12723,"library":"dependency-cruiser","title":"Dependency Cruiser","description":"Dependency Cruiser is a static analysis tool for validating and visualizing dependencies in JavaScript, TypeScript, and CoffeeScript projects, supporting various module systems including ES6, CommonJS, and AMD. Currently at version 17.3.10, the project demonstrates an active release cadence with frequent maintenance and feature updates. Key differentiators include its ability to define and enforce custom architectural rules, detect issues like circular dependencies or missing `package.json` entries, and generate highly customizable dependency graphs in multiple formats such as DOT, SVG, Mermaid, JSON, HTML, or plain text. It offers both a command-line interface for quick analysis and reporting, and a programmatic API for deeper integration into build processes or custom tooling.","status":"active","version":"17.3.10","language":"javascript","source_language":"en","source_url":"https://github.com/sverweij/dependency-cruiser","tags":["javascript","static analysis","circular","dependencies","typescript","coffeescript","ES6","ES2015"],"install":[{"cmd":"npm install dependency-cruiser","lang":"bash","label":"npm"},{"cmd":"yarn add dependency-cruiser","lang":"bash","label":"yarn"},{"cmd":"pnpm add dependency-cruiser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for analyzing TypeScript projects. Dependency Cruiser can function without it for JavaScript, but for TS analysis, it expects `typescript` to be installed in the project or globally.","package":"typescript","optional":true},{"reason":"The `dot` command from Graphviz is required to render `.dot` output files into visual formats like SVG or PNG. This is an external system dependency, not an npm package.","package":"graphviz","optional":true}],"imports":[{"note":"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.","wrong":"const cruise = require('dependency-cruiser');","symbol":"cruise","correct":"import { cruise } from 'dependency-cruiser';"},{"note":"The `format` function, used to transform raw cruise results into various output formats, is a named export from the main package.","wrong":"import format from 'dependency-cruiser/format';","symbol":"format","correct":"import { format } from 'dependency-cruiser';"},{"note":"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.","wrong":"import { IConfiguration } from 'dependency-cruiser';","symbol":"IConfiguration","correct":"import type { IConfiguration } from 'dependency-cruiser';"}],"quickstart":{"code":"npm install --save-dev dependency-cruiser\nnpx depcruise --init\n# Answer prompts to generate .dependency-cruiser.js configuration\n\n# Run analysis and generate an SVG graph using Graphviz dot tool\nnpx depcruise src --include-only \"^src\" --output-type dot | dot -T svg > dependency-graph.svg\n\n# For programmatic use, e.g., in a CI/CD pipeline or custom script:\n// my-analysis.ts\nimport { cruise, format } from 'dependency-cruiser';\nimport type { IConfiguration, ICruiseResult } from 'dependency-cruiser';\n\nconst config: IConfiguration = {\n  forbidden: [\n    {\n      name: 'no-circular',\n      comment: 'This dependency is part of a circular relationship.',\n      severity: 'warn',\n      from: {}, to: { circular: true }\n    },\n    {\n      name: 'no-internal-to-external',\n      comment: 'Don\\'t allow internal code to depend on external libraries outside of an adapter layer.',\n      severity: 'error',\n      from: { path: '^src/(?!adapters)' },\n      to: { dependencyTypes: ['npm', 'npm-dev'] }\n    }\n  ],\n  options: {\n    // Configure to resolve TypeScript paths, etc.\n    tsPreCompilationDeps: true,\n    doNotFollow: {\n      path: 'node_modules'\n    },\n    moduleSystems: ['es6', 'cjs'],\n  }\n};\n\nasync function analyzeDependencies() {\n  try {\n    const { output, exitCode } = await cruise(\n      ['src'], // Files or globs to cruise\n      config\n    ) as ICruiseResult;\n\n    if (exitCode !== 0) {\n      console.error('Dependency violations found:\\n', output);\n    } else {\n      console.log('No dependency violations found.');\n    }\n\n    // Example of using format for custom reporting (e.g., HTML)\n    // const htmlReport = format(output, { outputType: 'html' });\n    // console.log(htmlReport);\n\n  } catch (error: any) {\n    console.error('Error during dependency cruising:', error.message);\n    process.exit(1);\n  }\n}\n\nanalyzeDependencies();\n","lang":"typescript","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":">=13.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=17.3.10"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install TypeScript: `npm install --save-dev typescript` (local) or `npm install -g typescript` (global).","cause":"Attempting to analyze a TypeScript project without `typescript` installed as a dependency or globally.","error":"Error: Cannot find module 'typescript'"},{"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`.","cause":"Using an output type directly (like `svg`) that `dependency-cruiser` doesn't generate natively; these formats require an external tool like `Graphviz`.","error":"Error: Unknown output type 'svg' (or 'png', 'jpg')"},{"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.","cause":"A circular dependency was detected in your codebase, violating a rule configured in `.dependency-cruiser.js`.","error":"ERROR: [no-circular] (dependency-graph.js) → main.js"},{"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.","cause":"Attempting to use `dependency-cruiser`'s programmatic API with CommonJS `require` syntax or without properly awaiting the `cruise` function after upgrading to v13+.","error":"TypeError: (0, dependency_cruiser_1.cruise) is not a function"}],"ecosystem":"npm"}