options-reference.md

Dependency cruiser options - reference

• Filters
  • doNotFollow: don't cruise modules any further
  • includeOnly: only include modules satisfying a pattern
  • focus: show modules matching a pattern - with their direct neighbours
  • reaches: show modules matching a pattern - with everything that can reach them
  • highlight: highlight modules
  • exclude: exclude dependencies from being cruised
  • collapse: summarize to folder depth or pattern
  • maxDepth
• Matching your environment
  • moduleSystems
  • tsPreCompilationDeps
  • tsConfig: use a TypeScript configuration file ('project')
  • babelConfig: use a babel configuration file
  • webpackConfig: use (the resolution options of) a webpack configuration
  • Yarn Plug'n'Play support - externalModuleResolutionStrategy
  • prefix: prefix links in reports
• reporterOptions
  • theme (dot, ddot and archi reporters)
  • summarising/ collapsePattern (dot and archi reporters)
  • filtering (dot, ddot and archi reporters)
  • wordlist - (anon reporter)
  • metrics
  • markdown
  • mermaid
  • text
• Esoteric options
  • preserveSymlinks
  • mono repo behaviour - combinedDependencies
  • exotic ways to require modules - exoticRequireStrings
  • extraExtensionsToScan
  • builtInModules: influencing what to consider built-in (/ core) modules
  • enhancedResolveOptions
  • forceDeriveDependents
  • experimentalStats
  • parser
  • cache
  • progress

Filters

Dependency-cruiser sports some filters that enable you to leave out certain parts of dependency-trees you're not particularly interested in. They work from the command line (as --do-not-follow, --include-only, --focus and --exclude respectively) but you can also specify them in the configuration file.

On the command line you can pass a single regular expression for each of them. The filters will use that to match against the (resolved) paths of modules in your dependency tree.

The configuration file gives a little bit more flexibility. Apart from the path you can specify additional properties, and pass an array of regular expressions (which in some instances will enhance legibility).

You can pass the path in one of three ways:

As a single regular expression:

options: {
  includeOnly: {
    path: "^bin|^src|^test|^packages",
  }
}

As an array of regular expressions:

options: {
  includeOnly: {
    path: ["^bin", "^src", "^test", "^packages"],
  }
}

Or in shorthand:

options: {
  includeOnly: ["^bin", "^src", "^test", "^packages"],
}

The next sections contain details on what each filter does and what extra attributes you can pass.

doNotFollow: don't cruise modules any further

🐚 command line option equivalent: --do-not-follow (string values passed to 'path' only)

If you do want to see certain modules in your reports, but are not interested in these modules' dependencies, you'd pass the regular expression for those modules to the doNotFollow option. A typical pattern you'd use with this is "node_modules":

    "options": {
      "doNotFollow": {
        "path": "node_modules"
      }
    }

Specifying dependency types in doNotFollow

It's not possible to use this on the command line

It is possible to specify a regular expression for files that dependency-cruiser should cruise, but not follow any further. In the options section you can restrict what gets cruised by specifying dependency types. So if e.g. you don't want dependency-cruiser to follow external dependencies, instead of specifying the "node_modules" path:

    "options": {
        "doNotFollow": {
            // "path": "node_modules",
            "dependencyTypes": [
                "npm",
                "npm-dev",
                "npm-optional",
                "npm-peer",
                "npm-bundled"
            ]
        }
    }

How doNotFollow influences what gets cruised

There's a few steps dependency-cruiser takes when you fire it of:

1. gather all files specified as an argument, filtering out the stuff in exclude and doNotFollow and that which is not in includeOnly.
2. starting from the gathered files: crawl all dependencies it can find. Crawling stops when a module matches doNotFollow rule or a modules' dependency matches either exclude or does not match includeOnly.
3. apply any rules over the result & report it.

So in the first step doNotFollow behaves itself exactly like exclude would. Only in the second step it allows files matching its pattern to be visited (but not followed any further).

This means dependency-cruise will encounter files matching doNotFollow but only when they are dependencies of other modules. This a.o. prevents unexpected behaviour where specifying node modules as doNotFollow pattern would still traverse all node_modules when the node_modules were part of the arguments e.g. in depcruise --do-not-follow node_modules --validate -- src test node_modules or, more subtly with depcruise --don-not-follow node_modules -- validate -- ..

includeOnly: only include modules satisfying a pattern

🐚 command line option equivalent: --include-only

In the includeOnly option you can pass a regular expression of all file paths dependency-cruiser should include in a cruise. It will discard all files not matching the includeOnly pattern.

This can be handy if you want to make an overview of only your internal application structure. E.g. to only take modules into account that are in the src tree (and exclude all node_modules, core modules and modules otherwise outside it):

"options": {
  "includeOnly": "^src/"
}

If you specify both an includeOnly and an exclude (see below), dependency-cruiser takes them both into account.

focus: show modules matching a pattern - with their neighbours

🐚 command line option equivalent: --focus

Just like the includeOnly option, focus takes a regular expressions you want dependency-cruiser to show in its output. In addition dependency-cruiser will include all neighbours of those modules. By default these will be direct dependencies and direct dependents - if you want more, you can use the depth attribute.

This can be useful if you just want to focus on one part of your application and how it interacts with the outside world.

basic use

Add a focus attribute in your options section. You will typically want to use this option in conjunction with one of the other filtering options, like doNotFollow or includeOnly as that will speed up the rendition quite a lot.

doNotFollow, includeOnly and exclude can run before dependency-cruiser does any static analysis, so dependency-cruiser applies as early on in the process as it can so it can prevent having to read files from disk (which is expensive).

It can only determine the modules in focus and their neighbours after applying static analysis, though, as only then it knows what the relationships between the modules are.

Example configuration:

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

sample command line invocation and graphical output

depcruise -src c focus.config.json -T dot | dot -T svg > focus.svg

adding depth

🐚 command line option equivalent: --focus-depth

With the depth attribute you can influence whether to include not only direct neighbours (depth: 1 - the default), but also their neighbours (depth: 2) etc. Just like with the maxDepth option, a depth of 0 is interpreted as infinite.

Example configuration:

{
  "options": {
    "includeOnly": "^src/",
    "focus": {
      "path": "^src/main/",
      "depth": 2
    }
  }
}

sample command line invocation and graphical output

depcruise src -c focus-depth-2.config.json -T dot | dot -T svg > focus-depth-2.svg

snazzy-up graphics with the 'matchesFocus' attribute

When dependency-cruiser applies focus on modules, it provides each module with a matchesFocus attribute, which is either true for modules in focus or false for the neighbours. You can use this attribute e.g. in your dot theme.

sample dot theme that uses matchesFocus + graphical output

{
  "options": {
    "includeOnly": "^src/",
    "focus": "^src/main/",
    "reporterOptions": {
      "dot": {
        "collapsePattern": "^node_modules/(@[^/]+/[^/]+|[^/]+)/",
        "theme": {
          "graph": {
            "splines": "ortho"
          },
          "modules": [
            {
              "criteria": { "matchesFocus": true },
              "attributes": {
                "fillcolor": "lime"
              }
            },
            {
              "criteria": { "matchesFocus": false },
              "attributes": {
                "fillcolor": "lightgray",
                "fontcolor": "gray"
              }
            }
          ]
        }
      }
    }
  }
}

When run...

depcruise src -c snazzy-focus.config.json -T dot | dot -T svg > snazzy-focus.svg

...it'll look something like this:

reaches: show modules matching a pattern - with everything that can reach them

🐚 command line option equivalent: --reaches

Just like the includeOnly and focus option, reaches takes a regular expression that dependency-cruiser uses to find modules to show in its output. In addition to what includeOnly does, dependency-cruiser will all dependents (direct and indirect) of the modules matched by the regular expression.

This can be useful if you want to make an impact analysis on what would be affected when you change one or more modules around.

Example configuration that'd filter out everything in src/report that can directly or indirectly reach the dependency-to-incidence-transformer module:

{
  "options": {
    "includeOnly": "^src/report",
    "reaches": "^src/report/utl/index.js"
  }
}

Which will look something like this when output through a dot reporter:

snazzy-up graphics with the 'matchesReaches' attribute

Just like with the focus filter option dependency-cruiser tags the modules that directly match the regular expression in the filter with matchesReaches: true and all other modules with matchesReaches: false. You can use this in the dot like reporter configurations to do some nice highlighting:

{
  "options": {
    "includeOnly": "^src/",
    "reaches": "^src/report/index.js",
    "reporterOptions": {
      "dot": {
        "theme": {
          "graph": {
            "splines": "ortho"
          },
          "modules": [
            {
              "criteria": { "matchesReaches": true },
              "attributes": {
                "fillcolor": "lime"
              }
            },
            {
              "criteria": { "matchesReaches": false },
              "attributes": {
                "fillcolor": "lightgray",
                "fontcolor": "gray"
              }
            }
          ]
        }
      }
    }
  }
}

Without this theming engaged the graph would look like this:

With the theming it looks like this:

highlight: highlight modules

🐚 command line option equivalent: --highlight

In contrast to all other 'filter' types this doesn't really filter anything. It will, however, label all modules that match the regular expression matchesHighlight boolean attribute. Reporters can use this to their advantage to apply special colors or fonts to the modules marked as such. The mermaid and dot reporters do this out of the box. The dot (and related, like ddot, archi and flat) reporter allows for some tweaking in the options.reporterOptions section of your .dependency-cruiser.js, the same way you can tweak the modules matched by the reaches or focus filters.

An example:

{
  "options": {
    "includeOnly": "^src/",
    "reaches": "^src/report/index.js",
    "reporterOptions": {
      "dot": {
        "theme": {
          "graph": {
            "splines": "ortho"
          },
          "modules": [
            {
              "criteria": { "matchesHighlight": true },
              "attributes": {
                "fillcolor": "yellow",
                "penwidth": 2
              }
            },
          ]
        }
      }
    }
  }
}

exclude: exclude dependencies from being cruised

🐚 command line option equivalent: --exclude (string values passed to 'path' only)

If you don't want to see certain modules in your report (or not have them validated), you can exclude them by passing a regular expression to the exclude. E.g. to exclude node_modules from being scanned altogether:

"options": {
  "exclude": {
    "path": "node_modules"
  }
}

Because it's regular expressions, you can do more interesting stuff here as well. To exclude all modules with a file path starting with coverage, test or node_modules, you could do this:

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

Other 'exclude' attributes

It's also possible to exclude dependencies on other properties than the (resolved) paths at either end of them. To exclude all dependencies that result of an (ECMAScript) dynamic import from being included in a cruise, you can use the dynamic attribute:

"options": {
  "exclude": {
    "dynamic": true
  }
}

Other attributes might come in future releases

collapse: summarize to folder depth or pattern

🐚 command line option equivalent --collapse

As this is an option that is probably typically used from the command line it's described primarily over there.

maxDepth

🐚 command line option equivalent: --max-depth

Only cruise the specified depth, counting from the specified root-module(s). This command is mostly useful in combination with visualization output like dot to keep the generated output to a manageable size.

Tip

If you use this to get a high level overview of your dependencies, be sure to check out the archi reporter. That's more flexible, while still taking into account all your rules and dependencies. You can also consider the collapse option for this.

This will cruise the dependencies of each file directly in the src folder, up to a depth of 1:

...
  "maxDepth": 1
...

With "maxDepth": 2 it'll look like this:

And with "maxDepth": 3 like this:

Tip

The maxDepth option is there to help with visualizing. If your goal is to validate this option is best left alone as you'll miss a dependency or two otherwise.

Matching your environment

moduleSystems

🐚 command line option equivalent: --module-systems

Here you can pass a list of module systems dependency-cruiser should use to detect dependencies. It defaults to ["es6", "cjs", "tsd", "amd"] The 'module systems' dependency-cruiser supports:

System	Meaning
es6	modules as defined for ECMAScript 6 in 2015 in Emma-262, with proper import and export statements
cjs	Common js as popularised by node.js which uses the require function to include other modules
tsd	TypeScript 'triple slash directives'
amd	Asynchronous Module Definition as used by a.o. RequireJS

tsPreCompilationDeps

🐚 command line option equivalent: --ts-pre-compilation-deps

By default dependency-cruiser does not take dependencies between typescript modules into account that don't exist after compilation to JavaScript.

Switch this option to true if you do want to take them into account (as a bonus this will make cruising typescript code bases faster).

If you want to define rules on whether dependencies exist only before compilation or also after (with preCompilationOnly) you can pass the value "specify" to this option. Only do this if you really need it as it will impact cruise speed. You can only use the "specify" value within dependency-cruiser configurations (not from the command line).

Pre-compilation dependencies example: only importing a type

As the JavaScript doesn't really know about types, dependencies on types only exist before, but not after compile time.

a.ts exports an interface ...

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

... and b.ts uses that interface:

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

After compilation b.js looks like this:

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

Normally, without tsPreCompilationDeps the output will look like this:

With tsPreCompilationDeps the dependency graph does include the dependency-on-a-type-only from b.ts to a.ts:

Pre-compilation dependencies example: import without use

Similarly, if you import something, but don't use it, the dependency only exists before compilation. Take for example these two typescript modules:

a.ts:

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

b.ts:

export class B {}

As a.ts uses none of the imports from b, the typescript compiler will omit them when compiling and yield this for a.js:

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

Hence, without tsPreCompilationDeps dependency-cruiser's output will look like this:

... and with tsPreCompilationDeps like this:

tsConfig: use a typescript configuration file ('project')

🐚 command line option equivalent: --ts-config

If dependency-cruiser encounters typescript, it compiles it to understand what it is looking at. If you have compilerOptions in your tsconfig.json you think it should take into account, you can use this option to make it do that. You might want to do this e.g. if you have baseDir/ paths keys in your tsconfig, or are using jsx/ tsx outside of a react context.

Dependency-cruiser understands the extends configuration in tsconfig's so if you have a hierarchy of configs, you only need to pass the relevant one.

Sample

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

You can do it even more minimalistic like so (in which case dependency-cruiser will assume the fileName to be tsconfig.json)

"options": {
  "tsConfig": {}
}

On the command line

## use the `tsconfig.json` in the current directory into account when looking
## at typescript sources:
depcruise --ts-config --validate -- src

## use `tsconfig.prod.json for the same purpose:
depcruise --ts-config tsconfig.prod.json --validate -- src

Usage notes

• 💡 The configuration file you can pass as an argument to this option is relative to the current working directory.
• 💡 dependency-cruiser currently only looks at the compilerOptions key in the tsconfig.json and not at other keys (e.g. files, include and exclude).
• 💡 If you happen to use a jsconfig.json you can pass that as well as the syntax of the compilerOptions key is the same for both.

babelConfig: use a babel configuration file

🐚 there is no command line equivalent for this at the moment

If you're using babel you can tell dependency-cruiser so by telling it where your babel config lives, like this:

"options": {
  "babelConfig": {
    "fileName": ".babelrc"
  }
}

That way dependency-cruiser will use the babel compiler for its transpilation steps, so if you're using features that are not TC39 stage 4 yet dependency-cruiser will happily analyze these source files for you.

If you only use a babel key in your package.json pass package.json as the babelConfig - dependency-cruiser will sort it out for you.

Usage notes

• 💡 In its current state dependency-cruiser will assume that all JavaScript and TypeScript sources it parses need to go through the babel compiler (regardless of the extension). This will cover the majority of the use cases for babel, but raise an issue if you need this to be configurable.
• 💡 Dependency-cruiser can process json (/ json5) configurations, either in a separate file or as a key in your package.json. It can also process .js , .cjs and .mjs configurations, as long as they export a simple javascript object. JavaScript configurations that export a function, might get supported in a later stage (upon request).
• 💡 Auto detection in --init looks at some of the likely suspects for babel configs - package.json (only if it contains a babel key), .babelrc, .babelrc.json, babel.config.json and any other file with babel in the name that ends on json or json5. - The feature currently works with babel versions >=7.0.0
• 🚧 The current implementation of babel support is robust, but can be more efficient. It's on the road map, but as it's not entirely trivial it may take some time. The implementation will be feature switched to guarantee stability.

webpackConfig: use (the resolution options of) a webpack configuration

🐚 command line option equivalent: --webpack-config
passing env and arguments is only available in the configuration file's options

Dependency-cruiser will pluck the resolve key from the webpack configuration you pass here and will use that information to resolve files on disk.

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

Or, shorter, to let dependency-cruiser pick the default webpack.config.js all by itself:

"options": {
  "webpackConfig": {}
}

If your webpack configuration exports a function that takes parameters, you can provide the parameters like so:

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

Usage notes

• 💡 The configuration file you can pass as an argument to this option is relative to the current working directory.
• 💡 If your webpack config exports an array of configurations, dependency-cruiser will only use the resolve options of the first configuration in that array.
• 💡 Configuration files in the node 'native' formats (.json, .js (both commonjs and ESM), .cjs, .mjs, .node) will load without configuration.
• 💡 formats of webpack configurations (TypeScript, yaml, livescript(!), json5 etc.) only work when the function is available that hacks nodejs into accepting the language type. This should already be the case in order for webpack-cli to parse the config in the first place, so that should hardly be an issue.
• 💡 For more information check out the the webpack resolve documentation.

Yarn Plug'n'Play support - externalModuleResolutionStrategy

🐚 there is no command line equivalent for this

This options is deprecated as per version 9.21.3; it's not necessary anymore as detection now happens automatically (enhanced_resolve supports it out of the box.)

In versions before 9.21.3 you could set it to use yarn's Plug'n'Play to resolve external modules; setting the externalModuleResolutionStrategy attribute to yarn-pnp would get you set for that - the default was node_modules

prefix: prefix links in reports

🐚 command line option equivalent: --prefix

If you want the links in the svg output to have a prefix (say, https://github.com/you/yourrepo/tree/master/) so when you click them you'll open the link on GitHub instead of the local file - pass that in the prefix option, e.g.:

...
  prefix: "https://github.com/sverweij/dependency-cruiser/tree/develop/"
...

Any URL works, so you can also use it to make sure links always open in your favorite editor. Here's an example for visual studio code:

...
  prefix: `vscode://file/${process.cwd()}/`,
...

💡 Make sure the prefix ends on a /.

baseDir: specify a directory to cruise from

🐚 there is no command line equivalent for this at the moment

By default dependency-cruiser will take the current working directory to start a cruise from. If you want to alter that you can pass it in this attribute.

reporterOptions

In the reporterOptions attribute you can pass things to reporters to influence their behaviour - for reporters that support this.

theme (dot, ddot and archi reporters)

Most representational aspects of the 'dot' reporter are customizable:

• On a global level, affecting all rendered modules and dependencies with graph, node and edge.
• Conditional - only affecting modules (or dependencies) that meet the criteria you specify with modules and dependencies.
  • You can use any module attribute and any dependency attribute for dependencies in the criteria of those.
  • If you provide an array of criteria for the attributes the module/ dependency will be matched if it matches any of the criteria.
  • For attributes you can use anything GraphViz dot can understand as an attribute (see their attributes documentation for a complete overview).

The criteria are evaluated top to bottom:

• Criteria higher up get precedence over the ones lower down.
• Criteria in the configuration file take precedence over the default ones.

For an extensive example you can have a look at the default theme dependency-cruiser ships with - default-theme.mjs.

theming examples

As a base, take this part of dependency-cruisers code:

base.config.js

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

The default template, with tweaks to get an 'engineering' like look (and all file names ending on .json a cylindrical look with a soft gradient):

engineering.config.js

module.exports = {
  extends: "./base.config.js",
  options: {
    reporterOptions: {
      dot: {
        theme: {
          replace: false,
          graph: {
            bgcolor: "dodgerblue",
            color: "white",
            fontcolor: "white",
            fillcolor: "transparent",
            splines: "ortho",
          },
          node: {
            color: "white",
            fillcolor: "#ffffff33",
            fontcolor: "white",
          },
          edge: {
            arrowhead: "vee",
            arrowsize: "0.5",
            penwidth: "1.0",
            color: "white",
            fontcolor: "white",
          },
          modules: [
            {
              criteria: { source: "\\.json$" },
              attributes: {
                shape: "cylinder",
                fillcolor: "#ffffff33:#ffffff88",
              },
            },
            {
              criteria: { coreModule: true },
              attributes: {
                color: "white",
                fillcolor: "#ffffff33",
                fontcolor: "white",
              },
            },
          ],
          dependencies: [
            {
              criteria: { resolved: "\\.json$" },
              attributes: { arrowhead: "obox" },
            },
          ],
        },
      },
    },
  },
};

To shift the dependency graph from a horizontal orientation to a vertical one, set the global graph attribute rankdir to TD (top down):

vertical.config.js

module.exports = {
  extends: "./base.config.js",
  options: {
    reporterOptions: {
      dot: {
        theme: {
          graph: { rankdir: "TD" },
        },
      },
    },
  },
};

To get output without any attributes and no conditional coloring you can order the default theme to be replaced by flipping the replace attribute to true.

bare

module.exports = {
  extends: "./base.config.js",
  options: {
    reporterOptions: {
      dot: {
        theme: {
          replace: true,
        },
      },
    },
  },
};

summarising/ collapsePattern (dot and archi reporters)

The dot reporter also supports the collapsePattern option originally created for the archi reporter, which summarizes modules matching the pattern to one node in the output. For the dot reporter the default is to not summarize anything, but you can make it do so anyway. A good candidate is the node_modules folder (provided you want that in your graph)

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/(@[^/]+/[^/]+|[^/]+))",
      },
    },
  },
};

The collapsePattern also accepts an array of regular-expressions-in-a-string to be consistent with how other regular expressions in the configuration file are handled.

archi

The 'customizable dot' (cdot) or 'archi' reporter exists to make high level dependency overviews. Out of the box it recognises structures that summarise to folders directly under packages, src, lib, and node_modules. You can adapt this behaviour by passing a collapsePattern to the archi reporterOptions in your dependency-cruiser configurations e.g. like so:

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

It also accepts the same theme option dot does. If you don't specify a theme, it'll use the one specified for dot or the default one if that one isn't specified either.

With the above collapsePattern and a custom dot scheme, the archi report for dependency-cruiser looks like this:

Modules collapsed in this fashion get the special attribute consolidated so they're easy to distinguish in a.o. themes. The default theme makes them a box3d shape (as you can see above) but if you want to use other attributes you can use the power of the theme mechanism to use your own e.g.

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

filtering (dot, ddot and archi reporters)

The level of detail you want to see in a visual representation can differ (quite a bit) from the detail you need for validation. This is the reason other graphical reporters exist as well, which collapse modules and their dependencies to either folders (ddot), or to a level you specify (archi).

With filters you can prune the dependency tree the dot reporter shows. It works on top of the cruise-level filters (includeOnly, exclude, focus, reaches and doNotFollow) and only for the reporter you configured it for.

The filters specified in the dot reporterOptions act as a fall back for the archi and ddot reporterOptions. This is because we found that often you want the same pruning for all visualizations.

The filters the reporterOptions.dot.filters support are includeOnly, exclude, focus and reaches.

Example:

module.exports = {
  options: {
    // this global doNotFollow option makes sure that dependency-cruiser
    // doesn't crawl any further when it encounters something with node_modules
    // in the name. The encountered module will be in the dependency-tree however
    doNotFollow: "node_modules",
    reporterOptions: {
      dot: {
        filters: {
          // makes sure only things in the src tree end up in the dot
          // report, and not things in node_modules, test or bin
          includeOnly: {
            path: "^src",
          },
        },
      },
    },
  },
};

Why would you use this over an extra cruise over the modules? If you have a lot of modules a cruise can take some time. Running a reporter takes relatively little time. You can leverage this knowledge by saving the results as json and then (with depcruise-fmt) run the various reporters over it. E.g.

# depcruise reads all specified modules from disk and parses them to infer
# dependencies. For big repos this can take a while
depcruise 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

Note: as of version 9.12.0 depcruise-fmt has filters as command line options that have the same effect, work on all reporters and might give you more flexibility.

depcruise-fmt -T dot results.json --include-only "^packages/search" | dot -T svg > search.svg
depcruise-fmt -T dot results.json --include-only "^packages/ancillaries" | dot -T svg > ancillaries.svg
depcruise-fmt -T dot results.json --include-only "^packages/checkout" | dot -T svg > checkout.svg

showMetrics - (dot and flat reporters)

With the showMetrics switch you can influence whether you want to show metrics in the graph or not (not is also the default).

Dependency-cruiser doesn't calculate these metrics by default - as likely not a lot of folks need them, and it does involve serious numbers of CPU-cycles to calculate them - switching the showMetrics option for these reporters to true will ensure metrics are calculated.

module.exports = {
  options: {
    reporterOptions: {
      dot: {
        showMetrics: true,
      },
    },
  },
};

This currently shows the instability metric next to the filename, e.g for the dot reporter like so:

wordlist - (anon reporter)

The anonymous reporter has a wordlist option to pass it a list of words to use to replace path elements with before it starts to generate random names. If you use the anonymous report a lot it can be beneficial to use a list of words so the output is repeatable (and easier to read).

{
  "options": {
    "reporterOptions": {
      "anon": {
        "wordlist": [
          "foo",
          "bar",
          "baz",
          "qux",
          "grault",
          "garply",
          "waldo",
          "fred"
        ]
      }
    }
  }
}

You're likely to need a lot of words to cover all your path elements if you want to prevent random names as much as possible. There's word lists in the wild that work exceptionally well - in the past I have used Sindre Sorhus' mnemonic-words list for this. If you use JavaScript as the configuration file format you can require or import it.

const mnemonicWords = require('mnemonic-words');

module.exports = {
  // ...
  options: {
    reporterOptions:
      anon: {
        wordlist: mnemonicWords
      }
  }
}

metrics

By default the metrics reporter emits instability metrics for all modules and folders, ordered by instability (descending). If you want to see less, or use a different sort order, you can tweak that with the metrics reporterOptions.

• hideModules: switch to true if you only want to see instability metrics for folders. Defaults to false.
• hideFolders: switch to true if you only want to see instability metrics for modules. Defaults to false.
• orderBy: with this you can specify how the metrics reporter orders its output. Defaults to instability. Possible values name, moduleCount, afferentCouplings, efferentCouplings, instability, size and topLevelStatementCount (the latter two only available when the experimentalStats option is set to true).

module.exports = {
  // ...
  options: {
    reporterOptions: {
      metrics: {
        hideModules: true, // hides the modules from the metrics reporter output
        // hideFolders: true, // would hide folders from the metrics reporter output
        orderBy: "name", // possible values: name, moduleCount, afferentCouplings, efferentCouplings, instability
      },
    },
  },
};

markdown

The markdown reporter by default delivers a report approximately as complete as the err-html reporter, including a title, a summary section, a details section and a footer. It might be you don't need that in your target situation (e.g. in a GitHub action job summary). This is why it is configurable. The markdown section in the options.reporterOptions section of your dependency-cruiser lets you configure what parts to leave in or out - and even what titles and headers the report should show:

module.exports = {
  // ...
  options: {
    reporterOptions: {
      markdown: {
        // Whether or not to show a title in the report. Defaults to true.
        showTitle: true,
        // The text to show as a title of the report.
        title: "## dependency-cruiser forbidden dependency check - results",

        // Whether or not to show a summary in the report
        showSummary: true,
        // Whether or not to give the summary a header
        showSummaryHeader: true,
        // The text to show as a header on top of the summary
        summaryHeader: "### Summary",
        // Whether or not to show high level stats in the summary
        showStatsSummary: true,
        // Whether or not to show a list of violated rules in the summary
        showRulesSummary: true,
        // Whether or not to show rules in the list of rules for which all violations are ignored.
        includeIgnoredInSummary: true,

        // Whether or not to show a detailed list of violations
        showDetails: true,
        // Whether or not to show ignored violations in the detailed list.
        includeIgnoredInDetails: true,
        // Whether or not to give the detailed list of violations a header
        showDetailsHeader: true,
        // The text to show as a header on top of the detailed list of violations
        detailsHeader: "### All violations",
        // Whether or not to collapse the list of violations in a <details> block
        // especially practical when the list of violations is still large.
        collapseDetails: true,
        // The text to in the <summary> section of the <details> block
        collapsedMessage: "Violations found - click to expand",
        // The text to show when no violations were found
        noViolationsMessage: "No violations found",

        // Whether or not to show a footer (with version & run date) at the bottom of the report
        showFooter: true,
      },
    },
  },
};

Example output

mermaid

By default the mermaid reporter delivers "compressed" results - This means that the rendered appearance remains the same, but the node is hashed and shortened. The default value for mermaid.js limits the amount of text that mermaid.js will render to 50000 characters.

However, it is also possible to output readable results without compression:

module.exports = {
  // ...
  options: {
    reporterOptions: {
      mermaid: {
        // Whether or not to compresses the output text. Defaults to true.
        minify: false,
      },
    },
  },
};

text

When you emit a text report you might want to see more clearly which modules you 'focussed' with the focus option and which are callers/ called. In order to do so you can pass an option that highlights focused modules (currently by underlining the focused modules).

module.exports = {
  // ...
  options: {
    reporterOptions: {
      text: {
        // Whether or not to highlight modules that are focused with the focus
        // option. Defaults to false.
        highlightFocused: true,
      },
    },
  },
};

Esoteric options

preserveSymlinks

🐚 command line option equivalent: --preserve-symlinks

Whether to leave symlinks as is or resolve them to their realpath. This option defaults to false - which is also nodejs' default behaviour since release 6.

mono repo behaviour - combinedDependencies

If combinedDependencies is on false (the default) dependency-cruiser will search for a package.json closest up from the source file it investigates. This is the behaviour you expect in a regular repo and in mono repos with independent packages. When in doubt keep this switch out of your config or set it to false.

Example

• monodash/
  • package.json
  • packages/
    • begindash/
      • package.json <- only look in this one
      • src/
        • index.ts

With combinedDependencies on true dependency-cruiser will merge dependencies from package.jsons from closest up from the source file until the place you started the cruise (typically the root of your monorepo). It 'll give precedence to the dependencies declared in the package.json closest to the file it investigates:

• monodash/
• package.json <- look in this one as well; merge it into the one down the tree
• packages/
  • begindash/
  • package.json <- look in this one
  • src/
  • index.ts

exotic ways to require modules - exoticRequireStrings

In some situations you might not be able to use the require function directly or at all. E.g. when you're not sure a module is present and want to have a fallback (semver-try-require). Or because require in your environment is used for something else and you needed to redefine require (const want = require; const whoa = want('whoadash')). Or because you're in AMD and you named the require parameter something else because of a company wide standard to do so.

In each of these cases you can still infer dependencies with the exoticRequireStrings option by adding an exoticRequireStrings array to the options in your dependency cruiser config.

E.g.:

"options": {
  "exoticRequireStrings": ["want", "tryRequire", "window.require"]
}

extraExtensionsToScan

The first step dependency-cruiser takes is to scan files and folders matching the arguments you passed it for files it can parse - typically TypeScript or JavaScript sources. Only in a next step it considers other file types, like when you include a picture from a .jsx. This approach means dependency-cruiser only finds these file types when they're reachable from parsable file types.

If you want to run orphan or reachability rules against these file types, however you might want include them in the first scan already. To do so you can pass their extensions in an extraExtensionsToScan array, like so:

"options": {
  "extraExtensionsToScan": [".json", ".jpg", ".webp", ".png"]
}

Warning

dependency-cruiser will take special care not to even read these files as it can't parse them anyway, and skipping them saves (sometimes a lot) of time. This also means that if you put an extension in the extra extensions to scan dependency-cruiser could have had parsed it won't.

builtInModules: influencing what to consider built-in (/ core) modules

By default dependency-cruiser considers nodejs built-in modules as core modules. In contexts that are not nodejs this might be not (entirely) right:

• when targeting the browser, the core modules are either not available or you're using a shim (e.g. the 1:1 copy of path on npmjs). In those cases dependency-cruiser should respectively flag the included core module as unresolvable or resolve it to node_modules/path
• when targeting a platform built on top of nodejs, like electron, you might want to specify the packages built into that platform as built-in/ core as well.

To override the default behaviour you can pass a builtInModules object in the options section of your dependency-cruiser configuration. The object has two attributes, that can be used on their own or combined:

• override: an array of strings with the names of the modules you want to use as core modules instead of the default ones. I.e. for a browser context you could use the empty array:

  options: {
    // ...
    builtInModules: {
      override: [];
    }
  }

• add: an array of strings with the names of the modules you want to add to the list of core modules. I.e. for electron you could use:

  options: {
    // ...
    builtInModules: {
      add: ["electron"];
    }
  }

enhancedResolveOptions

Under the hood dependency-cruiser uses webpack's enhanced-resolve. to resolve dependencies to disk. You can influence how dependency-cruiser uses it directly by passing resolver options in a webpack config for most things. If you do need to influence how dependency-cruiser does its resolution, but don't (want to) have a webpack config, you can use the enhancedResolveOptions section to set them.

exportsFields

List of strings to consider as 'exports' fields in package.json. Use ['exports'] when you use packages that use such a field and your environment supports it (e.g. node ^12.19 || >=14.7 or recent versions of webpack).

If you have an exportsFields attribute in your webpack config, that one will have precedence over the one specified here.

conditionNames

List of conditions to check for in the exports field. e.g. use ['imports'] if you're only interested in exposed es6 modules, ['require'] for commonjs, or all conditions at once (['import', 'require', 'node', 'default']) if anything goes for you. Only works when the 'exportsFields' array is non-empty.

If you have an conditionNames attribute in your webpack config, that one will have precedence over the one specified here.

extensions

List of extensions to scan for when resolving. Typically you want to leave this alone as dependency-cruiser figures out what extensions to scan based on

1. what is available in your environment
2. in the order your environment (nodejs, typescript) applies the resolution itself.

However, if you want it to scan less you can specify so with the extensions attribute. E.g. when you're 100% sure you only have typescript & json and nothing else you can pass ['.ts', '.json'] - which can lead to performance gains on systems with slow i/o (like ms-windows), especially when your tsconfig contains paths/ aliases.

mainFields

A list of main fields in manifests (package.json-s). By default this is the main field only, but there are a few situations where you want to expand that list

• If you use packages that use a different field to indicate the main file (e.g. module or browser). module is especially interesting if you use ES modules and want to have dependency-cruiser resolve to the ESM version. As you might still want the 'main' field to be used as a fallback (as quite a lot of external packages will still be commonjs ), you would specify ['module', 'main'] here.
• If you use external packages that only expose types which only do that via 'types' and/ or 'typings' fields (instead of in exportFields) and you still want references to these types to be resolved, you can expand the array to ['main', 'types', 'typings']

Dependency-cruiser's --init scaffolding will automatically add the types and typing fields to the mainFields array. As of version 14.1.0 it will add the module field to the mainFields array if it detects the current module is of type module.

mainFiles

Likely you will not need to use this

A list of files to consider 'main' files, defaults to ['index']. Only set this when you have really special needs that that warrant it.

aliasFields

Likely you will not need to use this

If you use a package that, in stead of the main field, or exports still uses the browser field to indicate the main file in case it's for the browser, you can use:

  {
  // ...
 "options": {
    // ...
    "aliasFields": [ "browser" ]
    // ...
  }
}

In typical enhanced-resolve fashion this field was added to support this scenario, but implemented in a more generic fashion. See resolve.alias in the webpack docs.

Defaults to an empty array (don't use any alias fields) to keep backwards compatibility.

cachedInputFileSystem - cacheDuration

Likely you will not need to use this

We want to have a slightly tighter control over the way enhanced-resolve accesses the file system as with the wrong settings a lot can go wrong. There's one thing you might still want the ability to change though, in a limited number of circumstances and that is the time enhanced resolve's files systems retains resolutions in memory.

With cacheDuration you can tweak the number of milliseconds enhanced-resolve's cached file system should use for cache duration. Typically you won't have to touch this - the default works well for repos up to 5000 modules/ 20000 dependencies, and likely for numbers above as well. If you experience memory problems on a (humongous) repository you can use the cacheDuration attribute to tame enhanced-resolve's memory usage by lowering the cache duration trading off against some (for values over 1000ms) or significant (for values below 500ms) performance. Dependency-cruiser currently uses 4000ms, and in the past has used 1000ms - both with good results.

E.g. to set the cache duration to 1337ms, you can use this:

{
  // ...
 "options": {
    // ...
    "enhancedResolveOptions": {
      "cachedInputFileSystem": {
        "cacheDuration": 1337
      }
    }
    // ...
  }
}

The cache duration is limited from 0ms (~ don't use a cache) to 1800000ms (0.5h).

The cacheDuration used here overrides any that might be set in webpack configs.

forceDeriveDependents

Dependency-cruiser will automatically determine whether it needs to derive dependents. However, if you want to force them to be derived, you can switch this variable to true.

experimentalStats

When set to true dependency-cruiser will emit an experimentalStats object in the result for each module. This feature is not yet used by any of the reporters dependency-cruiser ships with. The feature is also experimental which means it might disappear or change in the future.

parser

With this EXPERIMENTAL feature you can specify which parser you want to use as the primary parser: the acorn one, which handles all things javascript (commonjs, es-modules, jsx), or microsoft's tsc that can in addition parse typescript. At this time it's still possible to pass swc here, but that value is deprecated and will be removed in a future version.

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

swc and tsc only work when the compilers (respectively @swc/core and typescript) are installed in the same spot as dependency-cruiser is. They're not bundled with dependency-cruiser.

cache

🐚 command line option equivalent: --cache

Available from version 11.14.0.

Indicates if you want to use caching, and if so enables you to tweak how it operates.

The long form:

{
  // ...
 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),
      // is slower than 'metadata' and is a bleeding edge feature as of
      // version 12.5.0)
      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
    }
    // ...
  }
}

It's also possible to shorten this either by providing an empty object or true (= 'do use caching, but use the default settings'): cache: {} or cache: true.

For backwards compatibility you can give it a string as well - dependency-cruiser will interpret that as the cache folder.

{
  // ...
  options: {
    // cache dependency-cruiser results to a custom location
    cache: "some-folder/where-you-want-to-store/cache";
    // ...
  }
}

If you don't want to use caching you can leave the cache option out altogether or use cache: false.

As with most settings the command line option of the same name takes precedence of whichever is specified here.

See --cache: use a cache to speed up cruising in the command line documentation for more details on how the caching function currently operates.

progress

🐚 command line option equivalent: --progress (type only)

With this option you control whether or not dependency-cruiser shows progress information while it's running + what this information should look like.

See --progress: get feedback on what dependency-cruiser is doing while it's running Here too the command line option takes precedence over what is specified here.

In addition to what is possible on the command line you can specify a maximumLevel of messages you want dependency-cruiser to report progress on. For regular use a maximumLevel of 40 (summary) will provide sufficient feedback - higher levels can be useful for debugging dependency-cruiser.

// ...
options: {
  progress: {
    type: "performance-log",
    // options:
    // "cli-feedback" (the default)
    // "performance-log"
    // "none"
    maximumLevel: 50
    // allowed levels:
    // -1 (OFF)
    // 40 (summary)
    // 50 (info - the default)
    // 60 (debug)
    // 70 (trace)
    // 80 (extra strong)
    // 99 (absolutely everything)
  },
}
// ...