Skip to main content

​
What are Rules?

Rules are the building blocks of your Rev-dep configuration. Each rule targets a specific directory in your project and defines which checks should run on files within that scope.
Think of rules as isolated governance zones - each with its own set of quality standards and architectural constraints.

​
Rule Structure

Each rule in the rules array has the following structure: 
{
  "rules": [
    {
      "path": ".",
      "prodEntryPoints": [...],
      "devEntryPoints": [...],
      "followMonorepoPackages": true,
      "moduleBoundaries": [...],
      "circularImportsDetection": {...},
      "orphanFilesDetection": {...},
      // ... other checks
    }
  ]
}

​
Rule Properties

​
Path Configuration

​
path
string
required
Target directory path for this rule.
"path": "."
"path": "packages/client"
"path": "src/features/auth"
  • Use "." for the root directory
  • Paths must be relative to the config file location
  • Paths starting with "./" are automatically normalized
  • Paths containing "../" are rejected for security

​
Entry Points

​
prodEntryPoints
string[]
Production entry point glob patterns.
"prodEntryPoints": [
  "src/main.tsx",
  "src/pages/**/*.tsx",
  "src/server.ts"
]
Used as default entry points for:
  • orphanFilesDetection (if validEntryPoints not specified)
  • unusedExportsDetection (if validEntryPoints not specified)
  • devDepsUsageOnProdDetection (if prodEntryPoints not specified)
Define entry points that are actually loaded in production environments.
​
devEntryPoints
string[]
Development entry point glob patterns.
"devEntryPoints": [
  "scripts/**",
  "**/*.test.*",
  "**/*.spec.*",
  "**/*.stories.*"
]
Combined with prodEntryPoints as defaults for:
  • orphanFilesDetection.validEntryPoints
  • unusedExportsDetection.validEntryPoints
Include test files, scripts, and development-only code.

​
Monorepo Support

​
followMonorepoPackages
boolean | string[]
Control monorepo package resolution.
"followMonorepoPackages": true
"followMonorepoPackages": false
"followMonorepoPackages": ["@myorg/package-a", "@myorg/package-b"]
Values:
  • true (default): Follow all workspace packages
  • false: Disable workspace package resolution
  • ["pkg1", "pkg2"]: Follow only specified package names
When enabled, Rev-dep resolves imports between monorepo packages and validates cross-package dependencies.

​
Check Configuration

Each rule can enable specific checks. Most checks support both single object and array formats:

​
Single Detector (Most Common)

{
  "circularImportsDetection": {
    "enabled": true,
    "ignoreTypeImports": true
  }
}

​
Multiple Detectors (Advanced)

{
  "orphanFilesDetection": [
    {
      "enabled": true,
      "validEntryPoints": ["src/main.tsx"],
      "graphExclude": ["**/*.test.*"]
    },
    {
      "enabled": true,
      "validEntryPoints": ["scripts/build.ts"],
      "graphExclude": ["src/**/*"]
    }
  ]
}
Multiple detector instances allow you to run the same check with different configurations within a single rule.

​
Example Configurations

{
  "configVersion": "1.6",
  "rules": [
    {
      "path": ".",
      "prodEntryPoints": ["src/index.ts"],
      "devEntryPoints": ["**/*.test.ts"],
      
      "moduleBoundaries": [
        {
          "name": "core",
          "pattern": "src/core/**/*",
          "allow": ["src/utils/**/*"],
          "deny": ["src/ui/**/*"]
        }
      ],
      
      "circularImportsDetection": {
        "enabled": true,
        "ignoreTypeImports": true
      },
      
      "unusedExportsDetection": {
        "enabled": true,
        "autofix": true
      }
    }
  ]
}

​
Entry Point Inheritance

Some detectors inherit entry points from rule-level configuration:
If validEntryPoints is not specified in the detector config, it defaults to:
prodEntryPoints + devEntryPoints (merged and deduplicated)
Example:
{
  "prodEntryPoints": ["src/main.tsx"],
  "devEntryPoints": ["**/*.test.ts"],
  "orphanFilesDetection": {
    "enabled": true
    // Inherits: ["src/main.tsx", "**/*.test.ts"]
  }
}
If validEntryPoints is not specified, it defaults to:
prodEntryPoints + devEntryPoints (merged and deduplicated)
Exports from files matching these patterns are never reported as unused.
If prodEntryPoints is not specified in the detector config, it defaults to the rule-level prodEntryPoints.Example:
{
  "prodEntryPoints": ["src/main.tsx"],
  "devDepsUsageOnProdDetection": {
    "enabled": true
    // Inherits: ["src/main.tsx"]
  }
}

​
Running Specific Rules

You can run a subset of rules using the --rules flag: 
# Run only the client package rule
rev-dep config run --rules packages/client

# Run multiple specific rules
rev-dep config run --rules "packages/client,packages/server"
Use this during development to speed up iteration on specific packages.

​
Best Practices

Begin with basic checks enabled and gradually add more strict rules:
  1. Start with circularImportsDetection and unresolvedImportsDetection
  2. Add unusedNodeModulesDetection and missingNodeModulesDetection
  3. Introduce moduleBoundaries for architecture enforcement
  4. Enable unusedExportsDetection and orphanFilesDetection with autofix
Too few rules: Harder to configure different checks for different areasToo many rules: Slower execution, harder to maintainGood balance:
  • One rule per monorepo package
  • One rule per major feature domain
  • Separate rules for frontend/backend if in same repo
Accurate entry points are critical for:
  • Orphan file detection
  • Unused exports detection
  • Dev dependencies detection
Good entry points:
"prodEntryPoints": [
  "src/main.tsx",          // Main app entry
  "src/pages/**/*.tsx",    // Next.js pages
  "src/server.ts"          // Server entry
],
"devEntryPoints": [
  "scripts/**",            // Build scripts
  "**/*.test.*",           // Tests
  "**/*.stories.*"         // Storybook stories
]
For monorepo projects, enable followMonorepoPackages to:
  • Resolve cross-package imports correctly
  • Detect missing package.json dependencies
  • Enforce boundaries between packages
{
  "path": "packages/client",
  "followMonorepoPackages": true,
  "moduleBoundaries": [
    {
      "name": "no-server-imports",
      "pattern": "**/*",
      "deny": ["../../packages/server/**/*"]
    }
  ]
}

​
Troubleshooting

Symptoms: Warning message "No files found for this rule"Causes:
  • Incorrect path value
  • All files excluded by ignoreFiles
  • Path doesn’t exist
Solution:
  • Verify the path is correct relative to config file
  • Check global ignoreFiles patterns
  • Ensure the directory contains analyzable files (.js, .ts, .jsx, .tsx)
Symptoms: Error about invalid rule pathCauses:
  • Path contains "../"
  • Empty path
  • Path with only "./"
Solution:
  • Use "." for root
  • Use subdirectory names without "./" prefix: "packages/client"
  • Never use "../" to go outside project
Symptoms: Warning about missing package.json in rule pathImpact:
  • Node modules detection won’t work
  • Monorepo package resolution may fail
Solution:
  • Ensure each rule path has a package.json file
  • For monorepo packages, each package should have its own package.json

​
Next Steps

Available Checks

Explore all check types and their configuration

Module Boundaries

Enforce architectural constraints

Import Conventions

Standardize import styles

Config File Reference

Complete config schema documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us