Skip to main content
Fallow works out of the box with zero configuration. To customize entry points, rules, or ignore patterns, create a config file: 
fallow init          # Creates .fallowrc.json
fallow init --toml   # Creates fallow.toml

​
Config file formats

Fallow searches for config files in this order:
  1. .fallowrc.json (JSONC, comments allowed)
  2. fallow.toml
  3. .fallow.toml

​
Full example

{
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
  "entry": ["src/workers/*.ts", "scripts/*.ts"],
  "ignorePatterns": ["**/*.generated.ts", "**/*.d.ts"],
  "ignoreDependencies": ["autoprefixer", "@types/node"],
  "ignoreExports": [
    { "pattern": "src/public-api.ts", "exports": ["*"] }
  ],
  "rules": {
    "unused-files": "error",
    "unused-exports": "warn",
    "unused-types": "off",
    "unresolved-imports": "error"
  },
  "duplicates": {
    "mode": "mild",
    "minTokens": 50,
    "minLines": 5,
    "threshold": 10
  },
  "production": false
}

​
Config fields

Additional entry point glob patterns. Fallow auto-detects entry points from package.json (main, module, bin, exports) and framework plugins. Use this for files that aren’t auto-detected.
{
  "entry": ["src/workers/*.ts", "scripts/*.ts", "src/cli.ts"]
}
Even without an entry config, fallow automatically discovers entry points from your package.json fields. These files are treated as roots of the module graph. Anything reachable from them is considered “used.”Fallow reads the following package.json fields:
FieldDescription
mainCJS entry point
moduleESM entry point
types / typingsTypeScript declaration entry point
sourceUnbuilt source entry point (common convention for dev tooling)
browserBrowser-specific entry (string or object with per-path overrides)
binCLI binaries (string for single binary, object for multiple)
exportsModern entry point map (recursively resolved, including conditional exports and subpath patterns)
The exports field is resolved recursively: nested conditions like "import", "require", "types", and "default" are all followed to their target files. Subpath exports (e.g., "./utils") are included as well.Output directories (dist/, build/, out/, esm/, cjs/) referenced in these fields are mapped back to src/ equivalents with source extension fallback, since fallow ignores output directories by default.On top of package.json fields, framework plugins add their own entry points (e.g., Next.js adds pages/**, app/**/page.tsx; Vitest adds **/*.test.ts). Run fallow list to see all detected entry points.
Glob patterns for files to exclude from analysis entirely.
{
  "ignorePatterns": ["**/*.generated.ts", "**/*.d.ts", "legacy/**"]
}
Package names that should always be considered used.
{
  "ignoreDependencies": ["autoprefixer", "@types/node"]
}
Rules for ignoring specific exports. Useful for public API packages.
{
  "ignoreExports": [
    { "pattern": "src/index.ts", "exports": ["*"] },
    { "pattern": "src/utils/*.ts", "exports": ["default"] }
  ]
}
Configuration for fallow dupes:
{
  "duplicates": {
    "mode": "mild",
    "minTokens": 50,
    "minLines": 5,
    "threshold": 10
  }
}
Enable production mode to focus on code that ships to users.
{
  "production": true
}
Override configuration for specific workspace packages in a monorepo:
{
  "workspaces": {
    "packages/ui": {
      "entry": ["src/index.ts"],
      "ignoreExports": [
        { "pattern": "src/**/*.tsx", "exports": ["*"] }
      ]
    }
  }
}
Inherit from one or more base config files. This is useful for sharing configuration across projects or maintaining a base config with per-project overrides.
{
  "extends": ["./configs/base.json", "./configs/strict.json"]
}

extends = ["./configs/base.json", "./configs/strict.toml"]
Key behaviors:
  • Deep merge: Object fields (like rules) are deep-merged. The child config’s values override the base, but unspecified fields are inherited.
  • Array replacement: Array fields (like entry, ignorePatterns) are replaced entirely, not concatenated. If the child specifies entry, it overrides the base entry.
  • Cross-format support: A JSON config can extend a TOML config and vice versa.
  • Circular detection: Fallow detects circular extends chains and reports an error.
  • Max depth: Extends chains are limited to 10 levels to prevent accidental deep nesting.
  • String shorthand: A single path can be passed as a string instead of an array: "extends": "./base.json".
Paths are resolved relative to the config file that contains the extends field.
Apply different rules to specific file patterns. This is useful for relaxing rules in test files or tightening them in critical paths.
{
  "overrides": [
    {
      "files": ["*.test.ts", "*.spec.ts"],
      "rules": {
        "unused-exports": "off"
      }
    },
    {
      "files": ["src/core/**/*.ts"],
      "rules": {
        "unused-exports": "error",
        "unused-types": "error"
      }
    }
  ]
}

[[overrides]]
files = ["*.test.ts", "*.spec.ts"]

[overrides.rules]
unused-exports = "off"

[[overrides]]
files = ["src/core/**/*.ts"]

[overrides.rules]
unused-exports = "error"
unused-types = "error"
Each override object has:
  • files: Array of glob patterns matched against project-relative paths.
  • rules: Rule severity overrides that apply to files matching the patterns.
When multiple overrides match the same file, later overrides take precedence.
Avoid overly broad ignorePatterns. They exclude files from analysis entirely. Use ignoreExports for finer control over which exports are considered used.

​
JSON Schema

The $schema field enables autocomplete and validation in your editor: 
{
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json"
}
Generate it locally: 
fallow config-schema > schema.json

​
See also

Rules & Severity

Control issue severity for incremental CI adoption.

Inline Suppression

Suppress individual findings directly in source code.

Custom Plugins

Extend fallow with framework-specific entry point detection.