Configuration reference
The oxcruise config file.
Oxcruise reads oxcruise.config.ts or .oxcruiserc.json. See Configuration for a guide.
The config rejects keys that this page does not list.
A key of type string or a list takes globs. A leading ! negates a glob: ["src/**", "!src/**/*.test.ts"].
$schema
Type: string.
The URL or path of the JSON schema, for editors.
calls
Type: list of string.
Names of functions whose first string argument is a dependency, for example jest.mock.
categories
Type: object of Level, by name.
The level of each category of built-in rules. The categories are correctness, suspicious, style, restriction and nursery. The default is correctness: error, suspicious: warn.
doNotFollow
Type: string or a list.
Globs of modules that stay in the graph. Oxcruise does not parse their imports.
entries
Type: string or a list.
Files, directories or globs where the graph starts. The default is ["."].
extends
Type: list of string.
Paths to other config files. Their settings are the base, and this file changes them.
forbid
Type: list of ForbidRule.
Forbidden dependencies, written as rules.
ignorePatterns
Type: string or a list.
Globs of modules to leave out of the graph. Oxcruise also uses the rules of .gitignore when it looks for modules.
jsPlugins
Type: list of JsPlugin.
JS or TS plugins: paths or package names.
overrides
Type: list of Override.
Settings that change rules for some modules.
resolve
Type: ResolveSection.
How oxcruise resolves imports.
rules
Type: Rules.
The built-in and plugin rules, by name. A rule listed here wins over its category.
symbols
Type: boolean. Default: false.
Extract exports and the names that each import uses, for json output and plugins. Rules that need them enable this option.
Types
The keys above refer to these types.
AliasedPlugin
| Key | Type | Default | Description |
|---|---|---|---|
name (required) | string | The prefix of the rules: <name>/<rule>. It replaces the meta.name of the plugin. | |
specifier (required) | string | A path or a package name. |
Case
The case of a name.
| Value | Description |
|---|---|
"kebab-case" | my-file |
"camel-case" | myFile |
"pascal-case" | MyFile |
"snake-case" | my_file |
CircularFolder
One entry of folders: the folders whose dependencies on each other the rule checks.
| Key | Type | Default | Description |
|---|---|---|---|
path (required) | string or a list | Globs of the folders. {name} captures a path segment. A module below a matching folder belongs to it. A glob matches only the folder it names. |
ConventionFilter
Which conventions a rule takes into account: true (all, the default), false (none) or the names of the ones to use.
One of:
boolean- list of
string
DepSectionName
Allowed values: "dependencies" or "devDependencies" or "peerDependencies" or "optionalDependencies".
FolderStructureFolder
One entry of folders: the folders it matches and the checks for each of them.
| Key | Type | Default | Description |
|---|---|---|---|
allow | string or a list | Globs of the names that the files and folders directly in the folder can have. A glob that starts with ! forbids a name. A list of only such globs allows every other name. | |
case | Case | The case that the names of the files and folders directly in the folder must have. The rule checks the name before its first ., so Button.test.tsx is checked as Button. | |
message | string | Oxcruise shows this text instead of the generic message of the violations of this entry. | |
path (required) | string or a list | Globs of the folders to check. {name} captures a path segment, and require and allow can use the capture. A glob matches only the folder it names. A glob can also match a file. Then the checks apply to the folder of the file. | |
require | string or a list | Globs of the files and folders that must be in the folder. A glob is relative to the folder and can contain /. Each glob needs a match. |
ForbidRule
A dependency that the project does not allow. An import from a module that matches from to a target that matches to is a violation.
| Key | Type | Default | Description |
|---|---|---|---|
from | string or a list | Globs of the importing module. {name} captures a path segment, and to can use the capture. | |
level | Level | "error" | The level of the rule. |
message | string | Why the dependency is forbidden. Oxcruise shows it instead of the generic message. | |
name (required) | string | The name of the rule. Reports and overrides use it. | |
to | ToSpec | The target of the dependency: globs, or an object with conditions. |
JsPlugin
A JS or TS plugin: a path or package name, or an object that also gives the prefix of its rules.
One of:
string: A path, such as"./tools/acme.ts", or a package name, such as"acme". For a package name, oxcruise triesoxcruise-plugin-acmefirst and thenacme.AliasedPlugin: An object with the specifier of the plugin and the prefix of its rules.
Level
The level of a rule. off disables the rule, warn reports violations as warnings, and error reports them as errors.
Allowed values: "off" or "warn" or "error".
ModuleKind
What a module is. The names are the ones the config (to.kind), the JSON and plugins use.
| Value | Description |
|---|---|
"local" | A file of the project, parsed. |
"package" | A file inside node_modules: resolved, not parsed. |
"builtin" | A Node.js built-in module. |
"unresolved" | An import that could not be resolved. |
Override
Changes the settings of rules for some modules.
| Key | Type | Default | Description |
|---|---|---|---|
files (required) | string or a list | Globs of the importing modules that this override applies to. | |
rules | Rules | The built-in and plugin rules, by name. A rule listed here wins over its category. |
Relation
How two modules relate, for the relation condition.
| Value | Description |
|---|---|
"same-folder" | to is in the same folder as from. |
"descendant-of-from" | to is below the folder of from. |
"descendant-of-from-parent" | to is below the parent folder of from. |
"sibling" | to is in a sibling folder of from's folder. |
"same-package" | to is in the same workspace package as from. |
"cross-package" | to is in another workspace package than from. |
ResolveSection
How oxcruise resolves imports.
| Key | Type | Default | Description |
|---|---|---|---|
alias | object of string or a list, by name | Path aliases. For example { "~": "./src" }. | |
conditions | list of string | Export and import condition names. Oxcruise tries them before import, require, node and default. For example, use ["source"] to resolve workspace packages to their source. | |
tsconfig | string | The tsconfig for every file. By default, each file uses the nearest tsconfig. |
RuleEntry
The setting of a rule: a level, or an object with a level and the options of the rule.
One of:
Level- object of
any, by name
Rules
The built-in and plugin rules, by name. A rule listed here wins over its category.
| Key | Type | Default | Description |
|---|---|---|---|
circular-dependencies | Level or object | Reports dependencies that are part of a circular chain of imports. The message shows the shortest cycle through each dependency. | |
cross-package-relative-dependencies | Level or object | Reports relative imports that reach into another workspace package, for example ../other-package/src/x. | |
dependencies-on-tests | Level or object | Reports a non-test module that imports a test file or a test directory. Test files match *.test.* or *.spec.*. Test directories are test, tests, __tests__ and __mocks__. | |
deprecated-dependencies | Level or object | Reports imports of deprecated Node.js built-in modules and deprecated npm packages. | |
dev-dependencies-in-production | Level or object | Reports a production module that imports a package from devDependencies only. | |
duplicate-packages | Level or object | Reports a package that more than one package.json section declares, for example both dependencies and devDependencies. The rule ignores type-only imports. | |
folder-structure | Level or object | Checks the shape of the file tree: the files that a folder must have, the names that it can have, and the case of its names. The rule looks at all files in the entry folders, not only at modules. For the folders above the entry folders, such as the root folder, it knows their own files and folders, but not what is inside the other folders. It does not check those other folders. | |
layers | Level or object | Enforces a layered architecture: a layer can import only the layers that allow lists for it. The rule checks dependencies on local modules. Packages and built-in modules have no layer. | |
optional-dependencies | Level or object | Reports use of optional dependencies. An install can skip an optional dependency, so the package may not exist at runtime. | |
orphan-modules | Level or object | Reports modules that no other module imports and that import no module. | |
peer-dependencies | Level or object | Reports use of peer dependencies. The consuming project must provide a peer dependency. | |
undeclared-packages | Level or object | Reports imports of installed npm packages that no package.json section declares. | |
unresolved-dependencies | Level or object | Reports an import that oxcruise cannot resolve to a file or a package. | |
unused-exports | Level or object | Reports exports that no other module imports. The rule also reports: | |
unused-modules | Level or object | Reports source modules that no path from an entry point reaches. | |
unused-packages | Level or object | Reports a package that a package.json declares and that none of its modules imports. | |
visibility | Level or object | Restricts what a folder shows to the code outside it. A module inside a folder can import every module in that folder. A module outside it can import only the modules that the folder makes visible. The rule checks dependencies on local modules. |
ToCondition
Conditions on the dependency and the module it points to.
| Key | Type | Default | Description |
|---|---|---|---|
dynamic | boolean | The dependency is a dynamic import(). | |
kind | ModuleKind or a list | What the dependency points to. A dependency matches when it has any of these kinds. By default, every kind matches, except for reachable rules, which check only local and package modules. | |
path | string or a list | Globs that the target of the dependency must match. | |
reachable | boolean | to is reachable from from through other modules. | |
relation | Relation or a list | How to relates to from. A dependency matches when it has any of these relations. | |
typeOnly | boolean | The dependency is only import type or export type. |
ToSpec
One of:
stringor a list: Globs the dependency's target must match.ToCondition: An object with conditions on the dependency and its target.
VisibilityFolder
One entry of folders: a folder and what it shows to the code outside it.
| Key | Type | Default | Description |
|---|---|---|---|
message | string | Oxcruise shows this text instead of the generic message. | |
path (required) | string or a list | Globs of the folders. {name} captures a path segment, and public and private can use the capture. A glob matches only the folder it names. ** matches every folder. | |
private | string or a list | Globs of the modules in the folder that code outside it cannot import. A glob is relative to the folder. private wins over public. | |
public | string or a list | Globs of the modules in the folder that code outside it can import. A glob is relative to the folder. Without public, every module is public. |