Dependency Cruiser

https://github.com/sverweij/dependency-cruiser
Admin
Dependency Cruiser validates and visualizes dependencies in JavaScript, TypeScript, and CoffeeScript...
Tokens:90,594
Snippets:614
Trust Score:9.5
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Example output with --highlight

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Example output command for --highlight showing the whole code base. Suitable when your codebase is not that big.

```sh
npx dependency-cruiser src types --include-only '^(src|types)' --highlight "$(watskeburt main)" --config --output-type dot | dot -T svg > with-highlight.svg
```

--------------------------------

### Install dependency-cruiser with npm

Source: https://github.com/sverweij/dependency-cruiser/blob/main/docs/index.html

Install dependency-cruiser as a development dependency using npm.

```bash
npm i --save-dev dependency-cruiser
```

--------------------------------

### Prepare React repo for dependency-cruiser

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/real-world-samples.md

Clone the React repository, install dependencies, and download the dependency-cruiser config file.

```sh
git clone git@github.com:facebook/react.git
cd react
yarn
yarn add -D -W dependency-cruiser
rm -f react-dependency-cruiser-config.js
wget https://raw.githubusercontent.com/sverweij/dependency-cruiser/main/doc/real-world-samples/react-dependency-cruiser-config.js
```

--------------------------------

### base.config.js

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Base configuration for theming examples. Sets includeOnly and exclude options.

```javascript
module.exports = {
  options: {
    includeOnly: "^src/main",
    exclude: "/filesAndDirs/",
  },
};
```

--------------------------------

### dependency-cruiser CLI usage

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Shows the basic command line syntax for dependency-cruiser. Pass a list of files or directories to start cruising.

```sh
dependency-cruiser [options] <files-or-directories>
```

--------------------------------

### Cruise multiple files and directories

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Pass multiple files and directories as arguments to cruise them all in one go. This example cruises src, test, lib directories and index.ts file.

```sh
dependency-cruiser --output-type dot src test lib index.ts
```

--------------------------------

### Basic cruise example

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/api.md

Cruises all files in the 'src' folder and prints dependencies to stdout. Note that it recursively cruises everything including node_modules, which can be slow. Use cruise options to limit the scope.

```typescript
import { cruise, type IReporterOutput } from "dependency-cruiser";

const ARRAY_OF_FILES_AND_DIRS_TO_CRUISE: string[] = ["src"];
try {
  const cruiseResult: IReporterOutput = await cruise(
    ARRAY_OF_FILES_AND_DIRS_TO_CRUISE,
  );
  console.dir(cruiseResult.output, { depth: 10 });
} catch (pError) {
  console.error(pError);
}
```

--------------------------------

### Install dependency-cruiser with npm, yarn, or pnpm

Source: https://github.com/sverweij/dependency-cruiser/blob/main/README.md

Install dependency-cruiser as a dev dependency using npm, yarn, or pnpm. The commands are alternatives; choose the one matching your package manager.

```shell
npm install --save-dev dependency-cruiser
# or
yarn add -D dependency-cruiser
pnpm add -D dependency-cruiser
```

--------------------------------

### ndjson progress output example

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Command to run dependency-cruiser with --progress ndjson and redirect stderr to a file, followed by the typical ndjson output. The format is designed for detailed performance tests and may change without a major version bump.

```bash
dependency-cruiser src bin test configs types tools --no-cache -Tnull --progress ndjson 2>> performance-log.ndjson
```

```json
{"runStartTime":"2025-12-24T19:25:50.037Z","runId":213435185128416,"message":"startup: nodejs loading","time":297855,"elapsedTime":297855,"user":366111,"elapsedUser":366111,"system":48490,"elapsedSystem":48490,"rss":196329472,"heapUsed":78937168,"heapTotal":97124352,"external":11581186}
{"runStartTime":"2025-12-24T19:25:50.037Z","runId":213435185128416,"message":"startup: parse options","time":300133,"elapsedTime":2278,"user":368517,"elapsedUser":2406,"system":48671,"elapsedSystem":181,"rss":196706304,"heapUsed":79231160,"heapTotal":97124352,"external":11581226}
{"runStartTime":"2025-12-24T19:25:50.037Z","runId":213435185128416,"message":"startup: import analytical modules","time":315104,"elapsedTime":14971,"user":409243,"elapsedUser":40726,"system":52464,"elapsedSystem":3793,"rss":205144064,"heapUsed":57310320,"heapTotal":104366080,"external":2748843}
{"runStartTime":"2025-12-24T19:25:50.037Z","runId":213435185128416,"message":"startup: parse rule set","time":326651,"elapsedTime":11547,"user":430393,"elapsedUser":21150,"system":52820,"elapsedSystem":356,"rss":205635584,"heapUsed":70138952,"heapTotal":104366080,"external":2757035}
{"runStartTime":"2025-12-24T19:25:50.037Z","runId":213435185128416,"message":"startup: get resolve options","time":326741,"elapsedTime":90,"user":430467,"elapsedUser":74,"system":52836,"elapsedSystem":16,"rss":205635584,"heapUsed":70199840,"heapTotal":104366080,"external":2757035}
{"runStartTime":"2025-12-24T19:25:50.037Z","runId":213435185128416,"message":"extract","time":523713,"elapsedTime":196971,"user":803754,"elapsedUser":373287,"system":77658,"elapsedSystem":24822,"rss":333938688,"heapUsed":121507992,"heapTotal":227934208,"external":2688354}
{"runStartTime":"2025-12-24T19:25:50.037Z","runId":213435185128416,"message":"analyze","time":548901,"elapsedTime":25189,"user":843483,"elapsedUser":39729,"system":78831,"elapsedSystem":1173,"rss":336887808,"heapUsed":96978728,"heapTotal":230031360,"external":2688354}
{"runStartTime":"2025-12-24T19:25:50.037Z","runId":213435185128416,"message":"report","time":551008,"elapsedTime":2107,"user":847523,"elapsedUser":4040,"system":78948,"elapsedSystem":117,"rss":336904192,"heapUsed":99378056,"heapTotal":230031360,"external":2688354}

```

--------------------------------

### Use npx to run dependency-cruiser with a temporary TypeScript compiler

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/faq.md

Install the TypeScript compiler and dependency-cruiser temporarily using npx, then run dependency-cruiser to list dependencies of a TypeScript file. Use the -p option to provide compilers when running with npx.

```bash
npx -p typescript@4.3.5 -p dependency-cruiser@latest dependency-cruiser src -T text --focus src/main/index.ts
```

--------------------------------

### Command line invocation for basic focus

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Command line invocation for the basic focus example. It generates an SVG graph using the dot reporter.

```sh
dependency-cruiser -src c focus.config.json -T dot | dot -T svg > focus.svg
```

--------------------------------

### Migrate depcruise-baseline to dependency-cruiser --baseline

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Migration example showing how to replace the deprecated depcruise-baseline command with the dependency-cruiser --baseline option. The old command is removed and the new one is added, using the same arguments.

```diff
- depcruise-baseline src test
+ dependency-cruiser src test --baseline
```

--------------------------------

### Command line invocation for snazzy focus

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Command line invocation for the snazzy focus example. It generates an SVG graph using the dot reporter.

```sh
dependency-cruiser src -c snazzy-focus.config.json -T dot | dot -T svg > snazzy-focus.svg
```

--------------------------------

### Command line invocation for focus with depth

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Command line invocation for the focus with depth example. It generates an SVG graph using the dot reporter.

```sh
dependency-cruiser src -c focus-depth-2.config.json -T dot | dot -T svg > focus-depth-2.svg
```

--------------------------------

### Extend a local base config (JSON)

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-reference.md

Use a local base config by specifying its path relative to the current file. The path must start with `./` for local files.

```json
{
  "extends": "./configs/dependency-cruiser-base.json"
}
```

--------------------------------

### Use --focus to show modules and neighbours

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Use this command to inspect a module or folder and see its direct dependencies and dependents. The --focus option takes a regular expression, and the example focuses on "^src/main" while including only "^src".

```sh
dependency-cruiser src --include-only "^src" --focus "^src/main" -T dot | dot -T svg > focus-on-main-dir-graph.svg
```

--------------------------------

### Use --do-not-follow (-X) to skip dependencies

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Use this command to include modules matching the pattern in reports but not follow their dependencies. The -X flag takes a regular expression, and the example uses "^node_modules" to avoid cruising into node_modules.

```sh
dependency-cruiser -X "^node_modules" -T html -f deps-with-unfollowed-node_modules.html src
```

--------------------------------

### Migrate depcruise-baseline with --output-to to dependency-cruiser --baseline

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Migration example showing how to replace the deprecated depcruise-baseline command with the dependency-cruiser --baseline option when specifying an alternative output location. The old command uses --output-to, while the new option takes the location directly after --baseline.

```diff
- depcruise-baseline src test --output-to my-baseline.json
+ dependency-cruiser src test --baseline my-baseline.json
```

--------------------------------

### Add dependency-cruiser scripts to package.json for Yarn 2 (berry)

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/real-world-samples.md

Add these two lines to the 'scripts' section of the package.json in the berry repo. Do not use the globally installed dependency-cruiser or even the locally installed one - yarn's pnp resolution won't work otherwise.

```json
"dc": "dependency-cruiser --version && dependency-cruiser --config berry-dependency-cruiser-config.js --output-type err packages",
"depcruise:archi": "dependency-cruiser --version && dependency-cruiser --config berry-dependency-cruiser-config.js --output-type archi packages | dot -T svg | tee berry-high-level-dependencies.svg | depcruise-wrap-stream-in-html > berry-high-level-dependencies.html",
```

--------------------------------

### Baseline update summary output

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Example output shown when --baseline updates an existing baseline file. Displays the total number of violations and counts for new, same, and stale entries.

```text
baseline  : 19 violations

  new     : 1
  same    : 18
  stale   : 8
```

--------------------------------

### Generate flat dependency graph for state-machine-cat

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/real-world-samples.md

Reproduces the flat graph for state-machine-cat: clones the repo, installs dependencies, runs dependency-cruiser with the flat output type, pipes to dot for SVG, saves the SVG, and wraps it in HTML.

```sh
git clone git@github.com:sverweij/state-machine-cat.git
cd state-machine-cat
npm install
npx dependency-cruiser src bin/smcat --progress \
    --config config/dependency-cruiser-graph.js \
    --output-type flat \
  | dot -Tsvg \
  | tee docs/dependency-cruiser-graph-flat-dot.svg \
  | npx depcruise-wrap-stream-in-html \
  > docs/dependency-cruiser-graph-flat-dot.html
```

--------------------------------

### Skeleton configuration with forbidden, allowed, required, options

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-reference.md

A minimal JSON configuration showing the four main sections: forbidden, allowed, required, and options. Use as a starting point for a dependency-cruiser config.

```json
{
  "forbidden": [],
  "allowed": [],
  "required": [],
  "options": {}
}
```

--------------------------------

### Configure archi reporter collapsePattern

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Configures the archi reporter's collapsePattern to summarize modules matching the pattern into one node. The archi reporter recognizes structures that summarize to folders directly under packages, src, lib, and node_modules by default; this example overrides that behavior.

```javascript
module.exports = {
  options: {
    reporterOptions: {
      archi: {
        collapsePattern: "^(src/[^/]+|bin)",
      },
    },
  },
};
```

--------------------------------

### Generate dependency graph SVG with dot output

Source: https://github.com/sverweij/dependency-cruiser/blob/main/README.md

Create a dependency graph of the src folder as an SVG. Requires GraphViz dot to be available. The --include-only option restricts the cruise to paths starting with 'src'.

```shell
npx dependency-cruiser src --include-only "^src" --output-type dot | dot -T svg > dependency-graph.svg
```

--------------------------------

### Ignored violations warning output

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Example output from the err/err-long reporters when known violations are ignored. Shows a warning that ignored violations exist and suggests running with --no-ignore-known to see them.

```text
✔ no dependency violations found (454 modules, 1078 dependencies cruised)
⚠ 20 known violations ignored. Run with --no-ignore-known to see them.
```

--------------------------------

### Generate SVG with prefixed links using --prefix

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Use the --prefix option to prepend a string to source file links in the dot output, useful for linking to an online repository. The example pipes the dot output to Graphviz to generate an SVG file.

```sh
dependency-cruiser --prefix "https://github.com/you/yourrepo/tree/master/" -T dot src | dot -T svg > dependency-graph-with-links-to-gh.svg
```

--------------------------------

### Using an array of regular expressions in dependency-cruiser rules

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-reference.md

Two equivalent JavaScript rule examples showing how to express a pathNot rule as a single regular expression string versus an array of regular expressions for better legibility. Both use group matching with $1 to reference the captured folder.

```javascript
{
  from: {
    path: "(^src/report/)"
  },
  to: {
    pathNot: "$1|^node_modules|^(path|package.json)$|^src/utl"
  }
}
```

```javascript
{
  from: {
    path: "(^src/report/)"
  },
  to: {
      pathNot: [
        "$1",
        "^node_modules",
        "^(path|package.json)$",
        "^src/utl"
      ]
  }
}
```

--------------------------------

### Configure dot reporter collapsePattern

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Configures the dot reporter's collapsePattern to summarize modules matching the pattern into one node. The default is to not summarize anything; this example collapses folders one step below node_modules, with a commented alternative for scoped packages.

```javascript
module.exports = {
  options: {
    reporterOptions: {
      dot: {
        // collapse onto folders one step below node_modules:
        collapsePattern: "^(node_modules/[^/]+)",
        // if you additionally collapse to scoped packages (@foo/bar, @foo/baz)
        // instead of just the scope (@foo) you can use this pattern:
        // collapsePattern: "^(node_modules/(@[^/]+/[^/]+|[^/]+))",
      },
    },
  },
};
```

--------------------------------

### Add JSDoc type import for configuration code completion

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/faq.md

Use this pattern in your .dependency-cruiser.js file to get code completion and suggestions in editors that support it. Newer versions of the --init generator automatically add this.

```javascript
/** @type {import('dependency-cruiser').IConfiguration} */
export default {
  // ... your rules & options
};
```

--------------------------------

### Use --focus-depth to set neighbour depth

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Use this command to control how many layers of neighbours --focus shows. The --focus-depth option accepts a value: 1 (default) means direct neighbours only, 2 shows neighbours' neighbours, and 0 means infinite. The example uses 0 to show all transitive neighbours.

```sh
dependency-cruiser src --include-only "^src" --focus "^src/main" --focus-depth 0 -T dot |\
  dot -T svg > focus-on-main-dir-graph.svg
```

--------------------------------

### tsConfig option: specify TypeScript config file

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Configure dependency-cruiser to use a TypeScript configuration file. The first example specifies the fileName explicitly; the second relies on the default fileName of tsconfig.json. The option is equivalent to the --ts-config command line flag.

```json
"options": {
  "tsConfig": {
    "fileName": "tsconfig.json"
  }
}
```

```json
"options": {
  "tsConfig": {}
}
```

--------------------------------

### webpackConfig option: use webpack resolve options

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Configure dependency-cruiser to use the resolve options from a webpack configuration. The first example specifies a custom file name; the second lets dependency-cruiser pick the default webpack.config.js; the third passes env and arguments to a webpack config that exports a function. The configuration file is relative to the current working directory, and only the first configuration is used if the webpack config exports an array.

```json
"options": {
  "webpackConfig": {
    "fileName": "webpack.config.js"
  }
}
```

```json
"options": {
  "webpackConfig": {}
}
```

```json
"options": {
  "webpackConfig": {
    "fileName": "webpack.config.js",
    "env": { "production": true },
    "arguments": { "mode": "production" }
  }
}
```

--------------------------------

### Customize archi theme for collapsed modules

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Customizes the archi reporter theme for collapsed modules. Modules collapsed via collapsePattern get the special attribute 'consolidated'; this example uses the theme mechanism to give them a 'tab' shape instead of the default 'box3d'.

```javascript
// ...
reporterOptions: {
 archi: {
   // ...
   theme: {
     modules: [
       {
         criteria: { collapsed: true },
         attributes: { shape: "tab" }
      }
    ]
  }
}
// ...
```

--------------------------------

### Mocha test structure with assert/strict and [I] prefix

Source: https://github.com/sverweij/dependency-cruiser/blob/main/AGENTS.md

Example Mocha test structure using Node's assert/strict. Group tests in describe blocks, use meaningful it descriptions, and test both success and error cases. Prefix describe titles with [U], [I], or [E] for unit, integration, or end-to-end tests.

```javascript
import { deepEqual, ok } from "node:assert/strict";
import functionToTest from "#path/to/function.mjs";

describe("[I] module/functionToTest", () => {
  it("should handle normal case", () => {
    const result = functionToTest(input);
    deepEqual(result, expectedOutput);
  });

  it("throws when given invalid input", () => {
    let error = null;
    try {
      functionToTest(invalidInput);
    } catch (pError) {
      error = pError;
    }
    ok(error instanceof Error);
  });
});
```

--------------------------------

### Get non-zero exit codes with depcruise-fmt -e

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Runs depcruise-fmt with the --exit-code flag to get non-zero exit codes when there are error-level dependency violations. Only works with output types that support non-zero exit codes (err, err-long, TeamCity).

```sh
depcruise-fmt -e cruise_result.json
```

--------------------------------

### err-long output type

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Similar to err, but also emits the comment associated with each violated rule for context. Useful in lint-staged setups.

```sh
dependency-cruiser --output-type err-long --config my-depcruise-rules.json src
```

--------------------------------

### Detect non-package.json dependencies with 'dependencyTypes'

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-reference.md

Detects dependencies that were installed without being saved to package.json. Flags dependency types 'unknown', 'undetermined', 'npm-no-pkg', and 'npm-unknown'.

```json
{
  "name": "no-non-package-json",
  "severity": "error",
  "comment": "because an npm i --production will otherwise deliver an unreliably running package",
  "from": { "pathNot": "^(node_modules)" },
  "to": {
    "dependencyTypes": ["unknown", "undetermined", "npm-no-pkg", "npm-unknown"]
  }
}
```

--------------------------------

### Use a reporter plugin via --output-type

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/faq.md

Command-line invocations to use a reporter plugin. The first uses a module name that dependency-cruiser must be able to resolve; the second provides a full path for local modules.

```bash
dependency-cruiser src --output-type plugin:my-awesome-plugin
```

```bash
dependency-cruiser src --output-type plugin:$(pwd)/path/to/my-awesome-plugin
```

--------------------------------

### Sample JSON output for commander.js

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/output-format.md

Sample JSON output from dependency-cruiser for the commander.js module. Shows the structure of the modules array with dependency details and the summary section with violation counts and options used.

```json
{
  "modules": [
    {
      "source": "commander/index.js",
      "dependencies": [
        {
          "resolved": "child_process",
          "coreModule": true,
          "followable": false,
          "couldNotResolve": false,
          "dependencyTypes": ["core"],
          "module": "child_process",
          "moduleSystem": "cjs",
          "valid": true,
          "circular": false
        },
        {
          "resolved": "events",
          "coreModule": true,
          "followable": false,
          "couldNotResolve": false,
          "dependencyTypes": ["core"],
          "module": "events",
          "moduleSystem": "cjs",
          "valid": true,
          "circular": false
        },
        {
          "resolved": "fs",
          "coreModule": true,
          "followable": false,
          "couldNotResolve": false,
          "dependencyTypes": ["core"],
          "module": "fs",
          "moduleSystem": "cjs",
          "valid": true,
          "circular": false
        },
        {
          "resolved": "graceful-readlink/index.js",
          "coreModule": false,
          "followable": true,
          "couldNotResolve": false,
          "dependencyTypes": ["npm"],
          "module": "graceful-readlink",
          "moduleSystem": "cjs",
          "valid": true,
          "circular": false
        },
        {
          "resolved": "path",
          "coreModule": true,
          "followable": false,
          "couldNotResolve": false,
          "dependencyTypes": ["core"],
          "module": "path",
          "moduleSystem": "cjs",
          "valid": true,
          "circular": false
        }
      ]
    },
    {
      "source": "child_process",
      "followable": false,
      "coreModule": true,
      "couldNotResolve": false,
      "dependencyTypes": ["npm"],
      "dependencies": []
    },
    {
      "source": "events",
      "followable": false,
      "coreModule": true,
      "couldNotResolve": false,
      "dependencyTypes": ["core"],
      "dependencies": []
    },
    {
      "source": "fs",
      "followable": false,
      "coreModule": true,
      "couldNotResolve": false,
      "dependencyTypes": ["core"],
      "dependencies": []
    },
    {
      "source": "path",
      "followable": false,
      "coreModule": true,
      "couldNotResolve": false,
      "dependencyTypes": ["core"],
      "dependencies": []
    },
    {
      "source": "graceful-readlink/index.js",
      "dependencies": [
        {
          "resolved": "fs",
          "coreModule": true,
          "followable": false,
          "couldNotResolve": false,
          "dependencyTypes": ["core"],
          "module": "fs",
          "moduleSystem": "cjs",
          "valid": true,
          "circular": false
        }
      ]
    }
  ],
  "summary": {
    "violations": [],
    "error": 0,
    "warn": 0,
    "info": 0,
    "totalCruised": 6,
    "optionsUsed": {
      "outputType": "json"
    }
  }
}
```

--------------------------------

### Exclude coverage, test, and node_modules paths

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Excludes all modules with file paths starting with coverage, test, or node_modules using a regular expression in the exclude.path option.

```json
"options": {
  "exclude": {
    "path": "^(coverage|test|node_modules)"
  }
}
```

--------------------------------

### Enable detectJSDocImports for JSDoc dependency detection

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/faq.md

Add this to your configuration to enable detection of dependencies declared in JSDoc/TSDoc comments. Requires the TypeScript parser and the `typescript` package to be installed.

```javascript
//...
detectJSDocImports: true; // implies `parser: tsc`
// ...
```

--------------------------------

### Run dependency-cruiser with text reporter and include-only filter

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Runs dependency-cruiser with the text reporter, including only modules under src/report, and outputs a flat dump of dependencies.

```sh
dependency-cruiser -T text --include-only src/report src/report
```

--------------------------------

### Run dependency-cruiser with --config

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Runs dependency-cruiser with a custom rules file. The --config option is optional as of version 13; use it only for an alternate name or location. Place -- after the last option to avoid interpreting a directory as the rules file.

```shell
dependency-cruiser -x node_modules --config my.rules.json src spec
```

--------------------------------

### Configure anon reporter wordlist

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Configuration snippet for the anon reporter to use a custom wordlist. The example uses the mnemonic-words package, which can be required in a JavaScript config file.

```javascript
...
options: {
  reporterOptions:
    anon: {
      wordlist: require('mnemonic-words')
    }
}
...
```

--------------------------------

### Generate config with npx dependency-cruiser --init

Source: https://github.com/sverweij/dependency-cruiser/blob/main/README.md

Generate a .dependency-cruiser.js configuration file. The command inspects your environment and asks questions to create a config tailored to your project. Using npx is for convenience; in package.json scripts you can omit the npx prefix.

```shell
npx dependency-cruiser --init
```

--------------------------------

### dot output type with GraphViz

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Generate a GraphViz dot directed graph. This example pipes the output to dot to produce an SVG. -T is short for --output-type.

```shell
dependency-cruiser -x "^node_modules" -T dot src | dot -T svg > dependencygraph.svg
```

--------------------------------

### depcruise-fmt --help output

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Shows the full help output for the depcruise-fmt command, including all options and their defaults. Use this to understand available flags for formatting dependency-cruiser JSON output.

```text
Usage: depcruise-fmt [options] <dependency-cruiser-json>

Format dependency-cruiser output json.
Details: https://github.com/sverweij/dependency-cruiser

Options:
  -f, --output-to <file>      file to write output to; - for stdout (default:
                              "-")
  -T, --output-type <type>    output type; e.g. err, err-html, dot, ddot, archi,
                              flat, baseline or json (default: "err")
  -I, --include-only <regex>  only include modules matching the regex
  -F, --focus <regex>         only include modules matching the regex + their
                              direct neighbours
  -x, --exclude <regex>       exclude all modules matching the regex
  -S, --collapse <regex>      collapse the modules to the regex pattern E.g.
                              ^packages/[^/]+/ collapses to modules/ folders
                              directly under your packages folder. Or pass a
                              single digit (e.g. 2) to collapse to a folder
                              depth.
  -e, --exit-code             exit with a non-zero exit code when the input
                              json contains error level dependency violations.
                              Works for err, err-long and teamcity output types
  -V, --version               output the version number
  -h, --help                  display help for command
```

--------------------------------

### Set parser to tsc

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Specify the primary parser as 'tsc' to enable TypeScript parsing. The 'swc' value is deprecated and will be removed. Requires the 'typescript' compiler to be installed alongside dependency-cruiser.

```javascript
{
  // ...
  options: {
    parser: "tsc";
  }
}
```

--------------------------------

### Generate HTML report with dependency-cruiser

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/sample-output.md

Runs dependency-cruiser with -c, -T html, and -f to write an HTML report to a specified file.

```sh
dependency-cruiser -c -T html -f stuff-for-alex/sample-dot-output.html test/fixtures
```

--------------------------------

### Regenerate fixtures with fixture regeneration scripts

Source: https://github.com/sverweij/dependency-cruiser/blob/main/tools/README.md

Run these scripts to regenerate fixtures and mocks after schema changes. Inspect results with git status and git diff to verify the desired outcome.

```sh
# Regenerate fixtures/ mocks associated with the main dependency-cruiser api
node tools/regenerate-main-fixtures.utl.mjs

# Regenerate fixtures/ mocks associated with the reporters
node tools/regenrate-report-fixtures.utl.mjs
```

--------------------------------

### Generate dot output with dependency-cruiser

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/sample-output.md

Runs dependency-cruiser with the -c flag (using config) and -T dot to produce a graph, then pipes it to dot to create a PNG image.

```sh
dependency-cruiser -c -T dot test/fixtures | dot -T png > sample-dot-output.png
```

--------------------------------

### Configure cache option with folder, strategy, and compress

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Configure the cache option with a folder, strategy ('metadata' or 'content'), and compress flag. The compress flag defaults to false; enabling it makes the cache file 80-90% smaller but adds a few milliseconds overhead.

```javascript
{
  // ...
 options: {
    cache: {
      // folder where dependency-cruiser will put its cache files
      folder: "node_modules/.cache/dependency-cruiser",
      
      // cache strategy to use - either 'metadata' (which uses git in the
      // background) or 'content' (which will look at file content (hashes))
      strategy: "metadata",

      // whether or not to compress the cache file. Switching this to true
      // will make dependency-cruiser a few milliseconds slower over all.
      // The resulting cache file will be 80-90% smaller though.
      // Defaults to false (don't compress)
      compress: false
    }
    // ...
  }
}
```

--------------------------------

### Import-without-use example for tsPreCompilationDeps

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Shows a.ts importing B from b.ts without using it. The compiled a.js drops the unused import, so the dependency only exists before compilation; tsPreCompilationDeps controls whether it is reported.

```typescript
import { B } from "./b";
export class A {}
```

```typescript
export class B {}
```

```javascript
// no imports here anymore...
export class A {}
```

--------------------------------

### Configure report-level filtering in dependency-cruiser config

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/faq.md

Add filters at the reporter level in the configuration to apply different filtering for graphs than for validations. This example shows only modules in the src tree for the dot reporter.

```json5
{
  "options": {
    // global filtering: when encountering node_modules record it
    // but don't follow it any further
    "doNotFollow": "node_modules",
    "reporterOptions": {
      "dot": {
        // filtering specific for the dot (graphical) reporter:
        // only show modules in the src tree
        "filters": {
          "includeOnly": { "path": "^src" }
        }
    }
  }
}
```

--------------------------------

### Basic focus configuration

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Basic configuration for the focus option. It shows modules matching the pattern and their direct neighbours. Typically used with includeOnly or doNotFollow for performance.

```json
{
  "options": {
    "includeOnly": "^src/",
    "focus": "^src/main/"
  }
}
```

--------------------------------

### Type-only import example for tsPreCompilationDeps

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Shows a.ts exporting an interface and b.ts importing it as a type-only dependency. The compiled b.js omits the import because it only referenced a type, illustrating why tsPreCompilationDeps is needed to detect such dependencies.

```typescript
import { B } from "./b";
export interface A {
  foo: string;
}
const b = new B();
```

```typescript
import { A } from "./a";
export class B {}
const a: A = { foo: "foo" };
```

```javascript
// import omitted as it only contained a reference to a type
export class B {}
const a = { foo: "foo" }; // no type refer
```

--------------------------------

### Generate dot graph with dependency-cruiser

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/real-world-samples.md

Generates the detailed 'dot' dependency graph for the dependency-cruiser repo. Uses --prefix vscode://file/$(pwd)/ so links open in vscode, pipes through dot to SVG, wraps into an interactive HTML graph, and opens it in the default browser. Replace node ./bin/dependency-cruiser.mjs with dependency-cruiser and node ./bin/wrap-stream-in-html.js with depcruise-wrap-stream-in-html for your own use.

```bash
# The --prefix will make sure that any links in the report open in vscode
# You can alternatively configure this in your .dependency-cruiser.js
node ./bin/dependency-cruiser.mjs bin src --prefix vscode://file/$(pwd)/ --config --output-type dot | \
  # format the output with dot
  dot -T svg |\
  # process the svg into an interactive html graph
  node ./bin/wrap-stream-in-html.js |\
  # The browser command opens the graph-in-html just produced in your
  # default browser
  browser
```

--------------------------------

### Recipe 1: Use a list of exceptions

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-tutorial.md

Defines a list of known dependents and uses it in two rules: one throws an error for any dependent not in the list, and one emits a warning for those in the list. Requires the list to be maintained manually.

```javascript
const KNOWN_DEPRECATED_THINGY_DEPENDENTS = [
  "^src/features/search/caramba\\.ts$"
  "^src/features/checkout/migusta\\.ts$"
  "^src/features/landing/sacrebleu\\.ts$"
  "^src/features/refund/donderju\\.ts$"
];

{
  forbidden: [
    // For anything pointing to deprecated-thingy that is not in the exceptions
    // throw an error
    {
      name: "not-to-deprecated-thingy",
      severity: "error"
      from: {
        pathNot: [
          "^src/common"
        ].concat(KNOWN_DEPRECATED_THINGY_DEPENDENTS)
      },
      to: {
        path: "^src/common/deprecated-thingy",
      }
    },
    // ... but emit a warning for known exceptions
    {
      name: "not-to-deprecated-thingy-known-exceptions",
      severity: "warn"
      from: {
        path: KNOWN_DEPRECATED_THINGY_DEPENDENTS,
        pathNot: [
          "^src/common"
        ]
      },
      to: {
        path: "^src/common/deprecated-thingy",
      }
    }
  ]
}

```

--------------------------------

### Find dependencies connected to meta module using grep

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Runs dependency-cruiser with the text reporter and pipes the output to grep to find all dependencies connected to the 'meta' module.

```sh
dependency-cruiser -c -T text src | grep transpile/meta.js
```

--------------------------------

### Sample output from azure-devops reporter

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Sample output from the azure-devops reporter showing error and warning log issues and a completion line with the result and counts.

```text
##vso[task.logissue type=error;sourcepath=src/asneeze.js;code=not-to-dev-dep;]src/asneeze.js -> node_modules/eslint/lib/api.js
##vso[task.logissue type=error;sourcepath=src/index.js;code=not-to-unresolvable;]src/index.js -> ./medontexist.json
##vso[task.logissue type=error;sourcepath=src/index.js;code=not-to-dev-dep;]src/index.js -> node_modules/eslint/lib/api.js
##vso[task.logissue type=warning;sourcepath=src/orphan.js;code=no-orphans;]src/orphan.js
##vso[task.complete result=Failed;]4 dependency violations (3 error, 1 warning/ informational). 8 modules, 7 dependencies cruised
```

--------------------------------

### Required rule for direct dependency on base controller

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-reference.md

A JavaScript configuration example for a required rule that checks for direct dependencies: modules matching the pattern must depend at least once on the base controller. The rule is named 'controllers-inherit-from-base'.

```javascript
{
  required: [
    {
      name: "controllers-inherit-from-base",
      comment:
        "Each controller should inherit from the framework's base controller",
      module: {
        // every module that matches the pattern specified in path & pathNot ...
        path: "-controller[.]js$",
        pathNot: "framework/base-controller[.]js$",
      },
      to: {
        // ... must depend at least once on the framework's base controller
        path: "^src/framework/base-controller[.]js$",
      },
    },
  ];
}
```

--------------------------------

### Run dependency-cruiser with azure-devops reporter

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Runs dependency-cruiser on the src directory using the .dependency-cruiser config and outputs Azure DevOps logging commands to stdout.

```shell
dependency-cruiser src -T azure-devops
```

--------------------------------

### Sample mermaid output from dependency-cruiser

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Sample mermaid flowchart output showing modules grouped by folder (src, test, node_modules) with dependencies and a style rule. This is the output of the mermaid reporter.

```mermaid
flowchart LR

subgraph src["src"]
  subgraph src_main["main"]
    subgraph src_main_rule_set["rule-set"]
      src_main_rule_set_normalize_js["normalize.js"]
    end
    src_main_index_js["index.js"]
    subgraph src_main_utl["utl"]
      src_main_utl_normalize_re_properties_js["normalize-re-properties.js"]
    end
  end
end
subgraph test["test"]
  subgraph test_enrich["enrich"]
    subgraph test_enrich_derive["derive"]
      subgraph test_enrich_derive_reachable["reachable"]
        test_enrich_derive_reachable_index_spec_mjs["index.spec.mjs"]
      end
    end
  end
  subgraph test_main["main"]
    subgraph test_main_rule_set["rule-set"]
      test_main_rule_set_normalize_spec_mjs["normalize.spec.mjs"]
    end
  end
  subgraph test_validate["validate"]
    test_validate_parse_ruleset_utl_mjs["parse-ruleset.utl.mjs"]
  end
end
subgraph node_modules["node_modules"]
  subgraph node_modules_lodash["lodash"]
    node_modules_lodash_has_js["has.js"]
    node_modules_lodash_cloneDeep_js["cloneDeep.js"]
  end
end
src_main_rule_set_normalize_js-->src_main_utl_normalize_re_properties_js
src_main_rule_set_normalize_js-->node_modules_lodash_cloneDeep_js
src_main_rule_set_normalize_js-->node_modules_lodash_has_js
src_main_index_js-->src_main_rule_set_normalize_js
test_enrich_derive_reachable_index_spec_mjs-->src_main_rule_set_normalize_js
test_main_rule_set_normalize_spec_mjs-->src_main_rule_set_normalize_js
test_validate_parse_ruleset_utl_mjs-->src_main_rule_set_normalize_js

style src_main_rule_set_normalize_js fill:lime,color:black
```

--------------------------------

### Typical --progress cli-feedback output

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Typical output of the --progress cli-feedback option, showing a one-line summary with a progress bar and percentage. It writes to stderr and is erased when done.

```text
  ◼◼◼◼◼◻◻◻◻ 60% reading files ...
```

--------------------------------

### Run multiple dependency-cruiser commands for different reporters

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Runs three separate dependency-cruiser commands to report violations, create an HTML report, and generate a dependency graph. This is the baseline approach without depcruise-fmt.

```sh
dependency-cruiser -c -T err-long src
dependency-cruiser -c -T err-html src -f violation-report.html
dependency-cruiser -c -T dot src | dot -T svg > dependency-graph.svg
```

--------------------------------

### Use --reaches to show transitive dependents

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Use this command to analyze which modules will be directly or indirectly affected by a change in one or more modules. The --reaches option takes a regular expression, and the example shows modules that can reach "^src/report/utl/index.js".

```sh
dependency-cruiser src --include-only "^src/report" --reaches "^src/report/utl/index.js" -T dot | dot -T svg > reaches-example.svg
```

--------------------------------

### Transpile and run TypeScript fixture with --allowJs

Source: https://github.com/sverweij/dependency-cruiser/blob/main/test/extract/__mocks__/ts/README.md

Transpile the TypeScript fixture with --allowJs, then run the resulting JavaScript. The output is a single line showing the exported version and a boolean check.

```sh
tsc --allowJs test/extract/fixtures/ts/index.ts
```

```sh
node test/extract/fixtures/ts/index.js
```

```text
1.0.0-exportedonly, 8 === 8 :
```

--------------------------------

### Use --config with -- separator

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md

Prevents the --config option from treating 'src' as the rules file by placing -- after the last option.

```shell
dependency-cruiser --config -- src
```

--------------------------------

### Run multiple reporters from saved JSON with depcruise-fmt

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md

Shows how to save a cruise result as JSON and then run multiple reporters via depcruise-fmt without re-cruising. The three formatting steps together take less time than a single cruise.

```sh
# dependency-cruiser reads all specified modules from disk and parses them to infer
# dependencies. For big repos this can take a while
dependency-cruiser src bin test -T json -c > results.json

# depcruise-fmt reads the result of a cruise and emits a report
# on it, so it doesn't need to do the expensive disk access & parse
# step. These three formatting steps together will take a lot less
# than even one cruise:
depcruise-fmt -T dot results.json | dot -T svg > module-graph.svg
depcruise-fmt -T archi results.json | dot -T svg > high-level-graph.svg
depcruise-fmt --exit-code -T err results.json
```

--------------------------------

### Group matching in dependency-cruiser rules

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-reference.md

Two JSON rule examples for the 'forbidden' section. The first flags all relations between business components, including within the same folder. The second adds a 'pathNot' with group matching ($1) to exclude relations within the same folder, preventing false positives.

```json
{
  "name": "no-inter-ubc",
  "comment": "Don't allow relations between code in business components",
  "severity": "error",
  "from": { "path": "^src/business-components/([^/]+)/.+" },
  "to": {
    "path": "^src/business-components/([^/]+)/.+"
  }
}
```

```json
{
  "name": "no-inter-ubc",
  "comment": "Don't allow relations between business components",
  "severity": "error",
  "from": { "path": "^src/business-components/([^/]+)/.+" },
  "to": {
    "path": "^src/business-components/([^/]+)/.+",
    "pathNot": "^src/business-components/$1/.+"
  }
}
```

--------------------------------

### Run transpiled JavaScript with node

Source: https://github.com/sverweij/dependency-cruiser/blob/main/test/main/__mocks__/cruise-reporterless/typescript/README.md

Command to run the transpiled JavaScript file.

```sh
node test/extract/fixtures/ts/index.js
```

--------------------------------

### Required rule for transitive dependency on base controller

Source: https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-reference.md

A JavaScript configuration example for a required rule that checks for indirect (transitive) dependencies: modules must depend on the base controller either directly or via other modules. The rule is named 'controllers-transitively-inherit-from-base' and uses the 'reachable: true' attribute.

```javascript
{
  required: [
    {
      name: "controllers-transitively-inherit-from-base",
      comment:
        "Each controller should inherit from the framework's base controller",
      module: {
        // every module that matches the pattern specified in path & pathNot ...
        path: "-controller[.]js$",
        pathNot: "framework/base-controller[.]js$",
      },
      to: {
        // ... must depend at least once on the framework's base controller
        path: "^src/framework/base-controller[.]js$",
        // ... either directly or indirectly
        reachable: true,
      },
    },
  ];
}
```
Tokens:
Raw