# dependency-cruiser

> Validate and visualize dependencies. With your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.

Latest version **18.3.1** (published 2026-09-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install dependency-cruiser
pnpm add dependency-cruiser
yarn add dependency-cruiser
bun add dependency-cruiser
```

Provides the commands `depcruise`, `depcruise-fmt`, `dependency-cruise`, `depcruise-baseline`, `dependency-cruiser`, `depcruise-wrap-stream-in-html`.

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 18.3.1 |
| Published | 2026-09-14 |
| First published | 2016-11-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^22\|\|^24\|\|>=26 |
| Dependencies | 18 |
| Unpacked size | 999.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 7175 |
| Author | Sander Verweij |
| Maintainers | sverweij, foureightone |
| Keywords | static analysis, circular, dependencies, typescript, javascript, coffeescript, ES6, ES2015, AMD, CommonJS, validation, spelunking |

## Links

- npm: https://www.npmjs.com/package/dependency-cruiser
- Repository: https://github.com/sverweij/dependency-cruiser
- Issues: https://github.com/sverweij/dependency-cruiser/issues
- npm.io page: https://npm.io/package/dependency-cruiser

## Dependencies (18)

- [acorn](https://npm.io/package/acorn.md) 8.18.0
- [json5](https://npm.io/package/json5.md) 2.2.3
- [ignore](https://npm.io/package/ignore.md) 7.0.9
- [semver](https://npm.io/package/semver.md) 7.8.5
- [prompts](https://npm.io/package/prompts.md) 2.4.2
- [rechoir](https://npm.io/package/rechoir.md) 0.8.0
- [acorn-jsx](https://npm.io/package/acorn-jsx.md) 5.3.2
- [commander](https://npm.io/package/commander.md) 15.0.0
- [interpret](https://npm.io/package/interpret.md) 3.1.1
- [picomatch](https://npm.io/package/picomatch.md) 4.0.7
- [acorn-walk](https://npm.io/package/acorn-walk.md) 8.3.5
- [safe-regex](https://npm.io/package/safe-regex.md) 2.1.1
- [watskeburt](https://npm.io/package/watskeburt.md) 6.0.0
- [acorn-loose](https://npm.io/package/acorn-loose.md) 8.5.2
- [acorn-jsx-walk](https://npm.io/package/acorn-jsx-walk.md) 2.0.0
- [enhanced-resolve](https://npm.io/package/enhanced-resolve.md) 5.25.1
- [is-installed-globally](https://npm.io/package/is-installed-globally.md) 1.0.0
- [tsconfig-paths-webpack-plugin](https://npm.io/package/tsconfig-paths-webpack-plugin.md) 4.2.0

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 18.3.1 (latest) — 2026-09-14
- 18.2.0-beta-2 (beta) — 2026-08-07
- 10.9.0 (version-10) — 2021-12-16
- 18.3.0 — 2026-09-13
- 18.2.0 — 2026-08-10
- 18.1.1 — 2026-08-02
- 18.1.0 — 2026-07-12
- 18.0.0 — 2026-06-25
- 18.0.0-beta-2 — 2026-06-22
- 18.0.0-beta-1 — 2026-05-30
- 17.4.3 — 2026-05-29
- 17.4.2 — 2026-05-23
- 17.4.0 — 2026-05-02
- 17.3.10 — 2026-03-26
- 17.3.9 — 2026-03-12
- … 571 more at https://npm.io/package/dependency-cruiser/versions

## README

# Dependency cruiser ![Dependency cruiser](https://raw.githubusercontent.com/sverweij/dependency-cruiser/main/doc/assets/ZKH-Dependency-recolored-160.png)

_Validate and visualise dependencies. With your rules._ JavaScript. TypeScript. CoffeeScript. ES6, CommonJS, AMD.

## What's this do?

![Snazzy dot output to whet your appetite](https://raw.githubusercontent.com/sverweij/dependency-cruiser/main/doc/assets/sample-dot-output.png)

This runs through the dependencies in any JavaScript, TypeScript, LiveScript or CoffeeScript project and ...

- ... **validates** them against (your own) [rules](./doc/rules-reference.md)
- ... **reports** violated rules
  - in text (for your builds)
  - in graphics (for your eyeballs)

As a side effect it can generate dependency graphs in various output formats including [**cool visualizations**](./doc/real-world-samples.md)
you can stick on the wall to impress your grandma.

## How do I use it?

### Install it ...

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

### ... and generate a config

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

This will look around in your environment a bit, ask you some questions and create
a `.dependency-cruiser.js` configuration file attuned to your project[^1][^2].

[^1]:
    We're using `npx` in the example scripts for convenience. When you use the
    commands in a script in `package.json` it's not necessary to prefix them with
    `npx`.

[^2]:
    If you don't want to use `npx`, but instead `pnpx` (from the `pnpm`
    package manager) or `yarn` - please refer to that tool's documentation.
    Particularly `pnpx` has semantics that differ from `npx` quite significantly
    and that you want to be aware of before using it. In the mean time: `npx`
    _should_ work even when you installed the dependency with a package manager
    different from `npm`.

### Show stuff to your grandma

To create a graph of the dependencies in your src folder, you'd run dependency
cruiser with output type `dot` and run _GraphViz dot_[^3] on the result. In
a one liner:

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

> <details>
> <summary>dependency-cruiser v12 and older: add --config option</summary>
>
> While not necessary from dependency-cruiser v13 and later, in v12 and older
> you'll have to pass the --config option to make it find the .dependency-cruiser.js
> configuration file:
>
> ```shell
> npx dependency-cruiser src --include-only "^src" --config --output-type dot | dot -T svg > dependency-graph.svg
> ```

</details>

- You can read more about what you can do with `--include-only` and other command line
  options in the [command line interface](./doc/cli.md) documentation.
- _[Real world samples](./doc/real-world-samples.md)_
  contains dependency cruises of some of the most used projects on npm.
- If your grandma is more into formats like `mermaid`, `json`, `csv`, `html` or plain text
  we've [got her covered](./doc/cli.md#--output-type-specify-the-output-format)
  as well.

[^3]:
    This assumes the GraphViz `dot` command is available - on most linux and
    comparable systems this will be. In case it's not, see
    [GraphViz' download page](https://www.graphviz.org/download/) for instructions
    on how to get it on your machine.

### Validate things

#### Declare some rules

When you ran `dependency-cruiser --init` above, the command also added some rules
to `.dependency-cruiser.js` that make sense in most projects, like detecting
**circular dependencies**, dependencies **missing** in package.json, **orphans**,
and production code relying on dev- or optionalDependencies.

Start adding your own rules by tweaking that file.

Sample rule:

```json
{
  "forbidden": [
    {
      "name": "not-to-test",
      "comment": "don't allow dependencies from outside the test folder to test",
      "severity": "error",
      "from": { "pathNot": "^test" },
      "to": { "path": "^test" }
    }
  ]
}
```

- To read more about writing rules check the
  [writing rules](./doc/rules-tutorial.md) tutorial
  or the [rules reference](./doc/rules-reference.md)

#### Report them

```sh
npx dependency-cruiser src
```

> <details>
> <summary>dependency-cruiser v12 and older: add --config option</summary>
>
> While not necessary from dependency-cruiser v13, in v12 and older you'll have
> to pass the --config option to make it find the .dependency-cruiser.js
> configuration file:
>
> ```shell
> npx dependency-cruiser --config .dependency-cruiser.js src
> ```

</details>

This will validate against your rules and shows any violations in an eslint-like format:

![sample err output](https://raw.githubusercontent.com/sverweij/dependency-cruiser/main/doc/assets/sample-err-output.png)

There's more ways to report validations; in a graph (like the one on top of this
readme) or in an self-containing `html` file.

- Read more about the err, dot, csv and html reporters in the
  [command line interface](./doc/cli.md)
  documentation.
- dependency-cruiser uses itself to check on itself in its own build process;
  see the `depcruise` script in the
  [package.json](https://github.com/sverweij/dependency-cruiser/blob/main/package.json#L76)

## I want to know more!

You've come to the right place :-) :

- Usage
  - [Command line reference](./doc/cli.md)
  - [Writing rules](./doc/rules-tutorial.md)
  - [Rules reference](./doc/rules-reference.md)
  - [Options reference](./doc/options-reference.md)
  - [FAQ](./doc/faq.md)
- Hacking on dependency-cruiser
  - [API](./doc/api.md)
  - [Output format](./doc/output-format.md)
  - [Adding other output formats](./doc/faq.md#q-how-do-i-add-a-new-output-format)
  - [Adding support for other alt-js languages](./doc/faq.md#q-how-do-i-add-support-for-my-favorite-alt-js-language)
- Other things
  - [Road map](https://github.com/sverweij/dependency-cruiser/projects/1)
  - [Contact](./doc/faq.md#contact)
  - [Real world show cases](./doc/real-world-samples.md)
  - [TypeScript, CoffeeScript and LiveScript support](./doc/faq.md#features)
  - [Support for .jsx, .tsx, .csx/ .cjsx, .vue and .svelte](./doc/faq.md#q-im-developing-in-react-and-use-jsx-tsx-csx-cjsx-how-do-i-get-that-to-work)
  - [Webpack alias/ modules support](./doc/faq.md#q-does-this-work-with-webpack-configs-eg-alias-and-modules)

## License

[MIT](LICENSE)

## Thanks

- [Marijn Haverbeke](http://marijnhaverbeke.nl) and other people who
  collaborated on [acorn](https://github.com/ternjs/acorn) -
  the excellent JavaScript parser dependency-cruiser uses to infer
  dependencies.
- [Katerina Limpitsouni](https://twitter.com/ninaLimpi) of [unDraw](https://undraw.co/)
  for the ollie in dependency-cruiser's
  [social media image](https://repository-images.githubusercontent.com/74299372/239ed080-370b-11ea-8fe7-140cf7b90a33).
- All members of the open source community who have been kind enough to raise issues,
  ask questions and make pull requests to get dependency-cruiser to be a better
  tool.

## Build status

[![GitHub Workflow Status](https://github.com/sverweij/dependency-cruiser/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/sverweij/dependency-cruiser/actions/workflows/ci.yml)
[![coverage](https://gitlab.com/sverweij/dependency-cruiser/badges/master/coverage.svg)](https://gitlab.com/sverweij/dependency-cruiser/builds)
[![total downloads on npm](https://img.shields.io/npm/dt/dependency-cruiser.svg?maxAge=2591999)](https://npmjs.com/package/dependency-cruiser)

Made with :metal: in Holland.

---
_Source: https://npm.io/package/dependency-cruiser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._