1 | # Dependency cruiser ![Dependency cruiser](https://raw.githubusercontent.com/sverweij/dependency-cruiser/master/doc/assets/ZKH-Dependency-recolored-160.png)
|
2 |
|
3 | _Validate and visualise dependencies. With your rules._ JavaScript. TypeScript. CoffeeScript. ES6, CommonJS, AMD.
|
4 |
|
5 | ## What's this do?
|
6 |
|
7 | ![Snazzy dot output to whet your appetite](https://raw.githubusercontent.com/sverweij/dependency-cruiser/master/doc/assets/sample-dot-output.png)
|
8 |
|
9 | This runs through the dependencies in any JavaScript, TypeScript, LiveScript or CoffeeScript project and ...
|
10 |
|
11 | - ... **validates** them against (your own) [rules](./doc/rules-reference.md)
|
12 | - ... **reports** violated rules
|
13 | - in text (for your builds)
|
14 | - in graphics (for your eyeballs)
|
15 |
|
16 | As a side effect it can generate [**cool dependency graphs**](./doc/real-world-samples.md)
|
17 | you can stick on the wall to impress your grandma.
|
18 |
|
19 | ## How do I use it?
|
20 |
|
21 | ### Install it
|
22 |
|
23 | - `npm install --save-dev dependency-cruiser` to use it as a validator in your project (recommended) or...
|
24 | - `npm install --global dependency-cruiser` if you just want to to inspect multiple projects.
|
25 |
|
26 | ### Show stuff to your grandma
|
27 |
|
28 | To create a graph of the dependencies in your src folder, you'd run dependency
|
29 | cruiser with output type `dot` and run _GraphViz dot_ on the result. In
|
30 | a one liner:
|
31 |
|
32 | ```shell
|
33 | depcruise --include-only "^src" --output-type dot src | dot -T svg > dependencygraph.svg
|
34 | ```
|
35 |
|
36 | - You can read more about what you can do with `--include-only` and other command line
|
37 | options in the [command line interface](./doc/cli.md) documentation.
|
38 | - _[Real world samples](./doc/real-world-samples.md)_
|
39 | contains dependency cruises of some of the most used projects on npm.
|
40 |
|
41 | ### Validate things
|
42 |
|
43 | #### Declare some rules
|
44 |
|
45 | The easy way to get you started:
|
46 |
|
47 | ```shell
|
48 | depcruise --init
|
49 | ```
|
50 |
|
51 | This will ask you some questions and create a `.dependency-cruiser.js` with some
|
52 | rules that make sense in most projects (detecting **circular dependencies**,
|
53 | dependencies **missing** in package.json, **orphans**, production code relying on
|
54 | dev- or optionalDependencies, ...).
|
55 |
|
56 | Start adding your rules by tweaking that file.
|
57 |
|
58 | Sample rule:
|
59 |
|
60 | ```json
|
61 | {
|
62 | "forbidden": [
|
63 | {
|
64 | "name": "not-to-test",
|
65 | "comment": "don't allow dependencies from outside the test folder to test",
|
66 | "severity": "error",
|
67 | "from": { "pathNot": "^test" },
|
68 | "to": { "path": "^test" }
|
69 | }
|
70 | ]
|
71 | }
|
72 | ```
|
73 |
|
74 | - To read more about writing rules check the
|
75 | [writing rules](./doc/rules-tutorial.md) tutorial
|
76 | or the [rules reference](./doc/rules-reference.md)
|
77 | - You can find the `--init-rules` set [here](./doc/rules.starter.json)
|
78 |
|
79 | #### Report them
|
80 |
|
81 | ```sh
|
82 | depcruise --config .dependency-cruiser.json src
|
83 | ```
|
84 |
|
85 | This will validate against your rules and shows any violations in an eslint-like format:
|
86 |
|
87 | ![sample err output](https://raw.githubusercontent.com/sverweij/dependency-cruiser/master/doc/assets/sample-err-output.png)
|
88 |
|
89 | There's more ways to report validations; in a graph (like the one on top of this
|
90 | readme) or in a table.
|
91 |
|
92 | - Read more about the err, dot, csv and html reporters in the
|
93 | [command line interface](./doc/cli.md)
|
94 | documentation.
|
95 | - dependency-cruiser uses itself to check on itself in its own build process;
|
96 | see the `decpruise` script in the
|
97 | [package.json](https://github.com/sverweij/dependency-cruiser/blob/master/package.json#L12)
|
98 |
|
99 | ## I want to know more!
|
100 |
|
101 | You've come to the right place :-) :
|
102 |
|
103 | - Usage
|
104 | - [Command line reference](./doc/cli.md)
|
105 | - [Writing rules](./doc/rules-tutorial.md)
|
106 | - [Rules reference](./doc/rules-reference.md)
|
107 | - [FAQ](./doc/faq.md)
|
108 | - Hacking on dependency-cruiser
|
109 | - [API](./doc/api.md)
|
110 | - [Output format](./doc/output-format.md)
|
111 | - [Adding other output formats](./doc/faq.md#q-how-do-i-add-a-new-output-format)
|
112 | - [Adding support for other alt-js languages](./doc/faq.md#q-how-do-i-add-support-for-my-favorite-alt-js-language)
|
113 | - Other things
|
114 | - [Road map](https://github.com/sverweij/dependency-cruiser/projects/1)
|
115 | - [Contact](./doc/faq.md#contact)
|
116 | - [Real world show cases](./doc/real-world-samples.md)
|
117 | - [TypeScript, CoffeeScript and LiveScript support](./doc/faq.md#features)
|
118 | - [Support for .jsx, .tsx, .csx/ .cjsx and .vue](./doc/faq.md#q-im-developing-in-react-and-use-jsx-tsx-csx-cjsx-how-do-i-get-that-to-work)
|
119 | - [Webpack alias/ modules support](./doc/faq.md#q-does-this-work-with-webpack-configs-eg-alias-and-modules)
|
120 |
|
121 | ## License
|
122 |
|
123 | [MIT](LICENSE)
|
124 |
|
125 | ## Thanks
|
126 |
|
127 | - [Marijn Haverbeke](http://marijnhaverbeke.nl) and other people who
|
128 | collaborated on [acorn](https://github.com/ternjs/acorn) -
|
129 | the excellent JavaScript parser dependency-cruiser uses to infer
|
130 | dependencies.
|
131 | - [Katerina Limpitsouni](https://twitter.com/ninaLimpi) of [unDraw](https://undraw.co/)
|
132 | for the ollie in dependency-cruiser's
|
133 | [social media image](https://repository-images.githubusercontent.com/74299372/239ed080-370b-11ea-8fe7-140cf7b90a33).
|
134 | - All members of the open source community who have been kind enough to raise issues,
|
135 | ask questions and make pull requests to get dependency-cruiser to be a better
|
136 | tool.
|
137 |
|
138 | ## Build status
|
139 |
|
140 | [![GitHub Workflow Status](https://img.shields.io/github/workflow/status/sverweij/dependency-cruiser/linting%20%26%20test%20coverage%20-%20linux?label=actions&logo=github)](https://github.com/sverweij/dependency-cruiser/actions)
|
141 | [![Build Status](https://travis-ci.org/sverweij/dependency-cruiser.svg?branch=master)](https://travis-ci.org/sverweij/dependency-cruiser)
|
142 | [![coverage](https://gitlab.com/sverweij/dependency-cruiser/badges/master/coverage.svg)](https://gitlab.com/sverweij/dependency-cruiser/builds)
|
143 | [![Maintainability](https://api.codeclimate.com/v1/badges/93035ef5fba33901d479/maintainability)](https://codeclimate.com/github/sverweij/dependency-cruiser/maintainability)
|
144 | [![Test Coverage](https://api.codeclimate.com/v1/badges/93035ef5fba33901d479/test_coverage)](https://codeclimate.com/github/sverweij/dependency-cruiser/test_coverage)
|
145 | [![total downloads on npm](https://img.shields.io/npm/dt/dependency-cruiser.svg?maxAge=2591999)](https://npmjs.com/package/dependency-cruiser)
|
146 |
|
147 | Made with :metal: in Holland.
|