Config file structure

To get started, initialise your config:

rev-dep config init

Rev-dep automatically detects project context and creates scaffolding for each workspace package it discovers.

The config file can be named rev-dep.config.json, rev-dep.config.jsonc, .rev-dep.config.json, or .rev-dep.config.jsonc depending on your preference.

Top-level fields

• configVersion: Configuration version string
• $schema: JSON schema reference for validation
• conditionNames: custom condition order for package.json imports/exports resolution.
• customAssetExtensions: additional extensions that should be treated as resolvable imports.
• ignoreFiles: files excluded from analysis by rev-dep config, in addition to gitignored files.
• processIgnoredFiles: files that should still be processed even if gitignore or ignore patterns would normally skip them.
• rules: array of rules defining checks for different parts of the codebase. Typically single rule defines checks for single workspace package. However, you can have multiple rules with the same path if that's needed.

Name rules might be confusing, it's a bad design choice made at the beginning. This will be likely renamed to workspaces or scopes in next major release to better reflect how it is actually being used.

Rule-level fields

Each rule must define:

• path - relative path to the workspace package that this rule applies to. Can be . for the root package.

And can additionally define:

• followMonorepoPackages: Control monorepo package resolution. true follows all workspace packages (default), false disables it, array follows only selected package names.
• prodEntryPoints: Rule-level production entry point patterns for detector defaults
• devEntryPoints: Rule-level development entry point patterns for detector defaults

And any detector setup:

• moduleBoundaries: Array of module boundary rules
• restrictedImportsDetection: Restrict importing denied files/modules from selected entry points
• importConventions: Array of import convention rules
• circularImportsDetection: Circular import detection configuration
• orphanFilesDetection: Orphan files detection configuration
• unusedExportsDetection: Unused exports detection configuration
• unusedNodeModulesDetection: Unused node modules detection configuration
• missingNodeModulesDetection: Missing node modules detection configuration
• devDepsUsageOnProdDetection: Restricted dev dependencies usage detection configuration
• unresolvedImportsDetection: Unresolved imports detection configuration

Detectors can be defined as a single object or an array of objects. Defining multiple configurations for the same detector allows to run it multiple times with different settings (e.g., different entry points or different deny rules for restricted imports) within the same rule.

Quick Start configuration

{
  "configVersion": "1.7",
  // enables json autocompletion
  "$schema": "https://github.com/jayu/rev-dep/blob/master/config-schema/1.7.schema.json?raw=true",
  "rules": [
    {
      "path": ".",
      "prodEntryPoints": ["src/main.tsx", "src/pages/**/*.tsx"],
      "devEntryPoints": ["scripts/**", "**/*.test.*"],
      "unusedExportsDetection": {
        "enabled": true,
        "autofix": true
      },
      "orphanFilesDetection": {
        "enabled": true,
        "autofix": true
      },
      "unusedNodeModulesDetection": { 
        "enabled": true 
      },
      "circularImportsDetection": { 
        "enabled": true 
      },
      "devDepsUsageOnProdDetection": {
        "enabled": true,
        "ignoreTypeImports": true
      }
    }
  ]
}

Use the schema URL for editor autocomplete and validation.

Comprehensive Config Example

Here's a comprehensive example showing all available properties:

{
  "configVersion": "1.7",
  // enables json autocompletion
  "$schema": "https://github.com/jayu/rev-dep/blob/master/config-schema/1.7.schema.json?raw=true", 
  "conditionNames": ["import", "default"],
  "ignoreFiles": ["**/*.test.*"],
  "rules": [
    {
      "path": ".",
      "followMonorepoPackages": true,
      "prodEntryPoints": ["src/main.tsx", "src/pages/**/*.tsx", "src/server.ts"],
      "devEntryPoints": ["scripts/**", "**/*.test.*"],
      "moduleBoundaries": [
        {
          "name": "ui-components",
          "pattern": "src/components/**/*",
          "allow": ["src/utils/**/*", "src/types/**/*"],
          "deny": ["src/api/**/*"]
        },
        {
          "name": "api-layer",
          "pattern": "src/api/**/*",
          "allow": ["src/utils/**/*", "src/types/**/*"],
          "deny": ["src/components/**/*"]
        }
      ],
      "importConventions": [
        {
          "rule": "relative-internal-absolute-external",
          "autofix": true,
          "domains": [
            {
              "path": "src/features/auth",
              "alias": "@auth",
              "enabled": true
            },
            {
              "path": "src/shared/ui",
              "alias": "@ui-kit",
              "enabled": false // checks disabled for this domain, but alias is still used for absolute imports from other domains
            }
          ]
        }
      ],
      "circularImportsDetection": {
        "enabled": true,
        "ignoreTypeImports": true
      },
      "orphanFilesDetection": {
        "enabled": true,
        "ignoreTypeImports": true,
        "graphExclude": ["**/*.test.*", "**/stories/**/*"],
        "autofix": true
      },
      "unusedNodeModulesDetection": {
        "enabled": true,
        "includeModules": ["@myorg/**"],
        "excludeModules": ["@types/**"],
        "pkgJsonFieldsWithBinaries": ["scripts", "bin"],
        "filesWithBinaries": ["scripts/check-something.sh"],
        "filesWithModules": [".storybook/main.ts"],
        "outputType": "groupByModule"
      },
      "missingNodeModulesDetection": {
        "enabled": true,
        "includeModules": ["lodash", "axios"],
        "excludeModules": ["@types/**"],
        "outputType": "groupByFile"
      },
      "unusedExportsDetection": {
        "enabled": true,
        "autofix": true,
        "ignoreTypeExports": true,
        "graphExclude": ["**/*.stories.tsx"],
        "ignore": {
          "src/types.ts": "B*",
          "**/generated/**/*.ts": "*"
        },
        "ignoreFiles": ["**/*.generated.ts"],
        "ignoreExports": ["default", "unused*"],
      },
      "unresolvedImportsDetection": {
        "enabled": true,
        "ignore": {
          "src/index.ts": "legacy-*"
        },
        "ignoreFiles": ["**/*.generated.ts"],
        "ignoreImports": ["@internal/*"]
      },
      "devDepsUsageOnProdDetection": {
        "enabled": true,
        "ignoreTypeImports": true
      },
      "restrictedImportsDetection": {
        "enabled": true,
        "entryPoints": ["src/server.ts", "src/server/**/*.ts"],
        "graphExclude": ["some-file-coupling-other-files.ts"],
        "denyFiles": ["**/*.tsx"],
        "denyModules": ["react", "react-*"],
        "ignoreMatches": ["src/server/allowed-view.tsx", "react-awesome-lib"],
        "ignoreTypeImports": true
      }
    }
  ]
}