Configuration

Configure fallow with .fallowrc.json, .fallowrc.jsonc, or fallow.toml. Customize entry points, ignore patterns, rules, and plugin settings for your project.

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. .fallowrc.jsonc (same JSONC parser, lets editors auto-detect JSON-with-comments syntax highlighting)
3. fallow.toml
4. .fallow.toml

Discovery is first-match-wins per directory, walking up to the workspace root. .fallowrc.json and .fallowrc.jsonc are identical in behavior; the .jsonc extension only signals to editors that comments are expected. If more than one of these files coexists in the same directory, fallow loads the higher-precedence one and prints a warning on stderr naming the file it ignored, so a stale config left over from a migration cannot silently win.

Full example

.fallowrc.json

{
  "$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": [
    { "file": "src/public-api.ts", "exports": ["*"] }
  ],
  "ignoreExportsUsedInFile": true,
  "publicPackages": ["@myorg/sdk"],
  "dynamicallyLoaded": ["src/plugins/**/*.ts"],
  "rules": {
    "unused-files": "error",
    "unused-exports": "warn",
    "unused-types": "off",
    // Opt-in API hygiene check; default is "off"
    "private-type-leaks": "warn",
    "unresolved-imports": "error"
  },
  "duplicates": {
    "mode": "mild",
    "minTokens": 50,
    "minLines": 5,
    "threshold": 10
  },
  "health": {
    "maxCyclomatic": 20,
    "maxCognitive": 15,
    "ignore": ["**/*.generated.ts"]
  },
  "audit": {
    "gate": "new-only"
  },
  "boundaries": {
    "preset": "bulletproof"
  },
  "production": false
}

Config fields

entry

Additional entry point glob patterns. Fallow auto-detects entry points from package.json (main, module, bin, exports) and framework plugins. Add files here that aren’t auto-detected.

{
  "entry": ["src/workers/*.ts", "scripts/*.ts", "src/cli.ts"]
}

Entry point auto-detection

Even without an entry config, fallow discovers entry points from your package.json fields. These files are the roots of the module graph. Anything reachable from them is considered “used.”

Fallow reads the following package.json fields:

Field	Description
main	CJS entry point
module	ESM entry point
types / typings	TypeScript declaration entry point
source	Unbuilt source entry point (common convention for dev tooling)
browser	Browser-specific entry (string or object with per-path overrides)
bin	CLI binaries (string for single binary, object for multiple)
exports	Modern entry point map (resolved recursively, 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 too.

Output directories (dist/, build/, out/, esm/, cjs/) referenced in these fields are mapped back to src/ equivalents with source extension fallback. 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.

ignorePatterns

Glob patterns for files to exclude from analysis entirely.

{
  "ignorePatterns": ["**/*.generated.ts", "**/*.d.ts", "legacy/**"]
}

ignoreDependencies

Package names that should always be considered used and always considered available. Listed dependencies are excluded from both unused dependency and unlisted dependency detection. Useful for runtime-provided packages like bun:sqlite or implicitly available dependencies.

{
  "ignoreDependencies": ["autoprefixer", "@types/node", "bun:sqlite"]
}

ignoreExports

Rules for ignoring specific exports. Useful for public API packages and for namespace-barrel UI libraries (shadcn / Radix / bits-ui) where many components/ui/<name>/index.ts files intentionally export the same short names.

ignoreExports suppresses both unused-export findings AND duplicate-export grouping for matching files. Use exports: ["*"] to exclude every export from the matched files; use a name list to exclude only those names.

{
  "ignoreExports": [
    { "file": "src/index.ts", "exports": ["*"] },
    { "file": "src/utils/*.ts", "exports": ["default"] },
    // shadcn / Radix / bits-ui barrels
    { "file": "src/lib/components/ui/**", "exports": ["*"] }
  ]
}

Note: per-file overrides.rules.duplicate-exports = "off" has no effect because the rule spans multiple files (a duplicate-export finding groups N locations across N files). Fallow emits a load-time warning when this override shape is detected and points at ignoreExports as the working escape hatch.

ignoreExportsUsedInFile

Suppress unused-export findings when the exported symbol is referenced inside the file that declares it. Exports with no references at all are still reported. Mirrors knip’s ignoreExportsUsedInFile.

{
  "ignoreExportsUsedInFile": true
}

A fine-grained object form is also accepted for knip parity:

{
  "ignoreExportsUsedInFile": { "type": true, "interface": true }
}

Fallow groups type aliases and interfaces under the same unused-types issue, so { "type": true }, { "interface": true }, and { "type": true, "interface": true } all behave identically: any type export referenced in the same file is suppressed. The two fields exist only for knip-config compatibility.

References inside the export specifier itself (export { foo }, export { foo as bar }, export default foo) do not count as same-file uses; those exports are still reported when no other file or no other in-file expression references the binding.

includeEntryExports

Report unused exports in entry files (package.json main/exports, framework pages, etc.) instead of auto-marking them as used. Catches typos in framework-convention exports like meatdata instead of metadata.

{
  "includeEntryExports": true
}

The same behaviour is also available as the global CLI flag --include-entry-exports. The CLI flag wins when both are set.

autoImports

Resolve framework convention auto-imports (Nuxt components) as real module-graph edges. Frameworks like Nuxt expose components to templates by filesystem convention (<Card001 /> resolving to components/Card001.vue) with no import statement.

{
  "autoImports": true
}

Edges for these tag references are always synthesized, so a component’s default export consumed via a <Card /> tag is credited under includeEntryExports. Setting autoImports: true additionally drops the Nuxt component entry patterns so a genuinely-unreferenced component is reported as unused-file instead of being kept alive as an entry point.

The flag is conservative: if your nuxt.config declares a components: key (custom prefix, pathPrefix, or dirs), the entry patterns are kept, since those custom layouts are not yet modeled. Defaults to false. Composable, util, and Pinia store auto-imports are tracked separately.

ignoreDecorators

Decorator names that fallow should NOT treat as evidence of reflective use. Members carrying only listed decorators are checked for usage like undecorated members. Members carrying any decorator NOT in the list stay skipped, so framework defaults (NestJS, Angular, TypeORM) are unchanged.

Use this when your codebase carries utility decorators that do not imply runtime reflection: Playwright’s @step("label"), internal labeling decorators like @measure, @log, @retry, or any custom decorator that wraps a method for logging or tracing.

{
  "ignoreDecorators": ["@step"]
}

Conservative semantics: a method decorated with both @step and @Inject stays skipped because @Inject is not in the ignore list. Only methods whose every decorator is in the list become subject to the standard usage check.

Matching

• Bare entries ("step" or "decorators") match the leftmost segment of the decorator path. A single bare "decorators" entry collapses every @decorators.* decorator, useful when an internal namespace exposes many utility decorators that should all be treated as non-reflective.
• Dotted entries ("decorators.log") match the full dotted path exactly. Sibling @decorators.audit decorators stay skipped unless you also list "decorators.audit" or use the bare "decorators" form.
• Both "@step" and "step" round-trip equivalently; a leading @ is stripped before matching.

Unmatched-entry warning

Entries that never match any decorator in the analyzed codebase produce a one-time warning at end of run, mirroring usedClassMembers’s warn-on-unmatched-pattern behavior. Treat unmatched entries as dead config and remove them.

The default empty list preserves today’s skip-all-decorated behavior, so existing NestJS / Angular / TypeORM projects see no change. The first run after enabling this option will surface new unused-class-members findings on members previously hidden by the unconditional skip.

usedClassMembers

Class member method/property names that should never be reported as unused. Extends fallow’s built-in Angular and React lifecycle allowlist with framework-invoked names from third-party libraries.

Use this when a library calls methods on your class at runtime via an interface or contract pattern. Common examples include ag-Grid (agInit, refresh), TypeORM migrations (up, down), and Web Components (connectedCallback, disconnectedCallback, attributeChangedCallback).

Each entry is either a plain member name (global suppression) or a scoped object that only matches classes whose heritage clause includes the configured extends or implements identifier. Strings can be exact names or glob patterns:

{
  "usedClassMembers": [
    "agInit",
    { "implements": "ICellRendererAngularComp", "members": ["refresh"] },
    { "extends": "BaseCommand", "members": ["execute"] },
    { "implements": "CanActivate", "members": ["canActivate"] },
    { "extends": "GrammarBaseListener", "members": ["enter*", "exit*"] }
  ]
}

Plain names like agInit are unique enough to suppress globally. Common names like refresh or execute would produce false negatives across unrelated classes, so scope them with implements or extends. A scoped rule requires at least one of extends or implements; an unconstrained object rule ({ "members": [...] } with no heritage field) is rejected at load time.

Heritage matching is syntactic: the identifier in the source’s extends Foo or implements IBar clause is compared against the rule’s string. Re-aliased imports (import { IBar as IBaz }) use whatever identifier appears in the class declaration.

Glob patterns

Member strings containing * or ? are treated as glob patterns; existing exact strings keep their current meaning. "*" matches every member declared on a matching class, "enter*" matches any member whose name starts with enter, "*Handler" matches any member ending with Handler, and "on*Event" combines prefix and suffix. Useful for parser-generator listeners (ANTLR), code-generated bridges, and abstract framework bases that dispatch on a member-name prefix instead of an exhaustive list.

Glob patterns that match zero members across the codebase emit a WARN at the end of the run so dead allowlist entries surface. Exact-string entries do not emit this warning (they are common boilerplate that may legitimately match in some configurations but not others).

The allowlist only applies to class methods and properties. Enum members with the same names are still checked.

For library-specific allowlists that should only activate when the library is installed, prefer a plugin file with the usedClassMembers field. See Custom plugins for the plugin format.

publicPackages

Workspace packages whose exported API surface should be considered public. Exports, exported enum members, and exported class members from these packages are never reported as unused, even if no internal consumer imports them. Useful for library packages that are consumed externally.

{
  "publicPackages": ["@myorg/sdk", "@myorg/types"]
}

dynamicallyLoaded

Glob patterns for files that are loaded dynamically at runtime (e.g., via import(), lazy routes, or plugin systems). These files are treated as entry points and will not be reported as unused.

{
  "dynamicallyLoaded": ["src/plugins/**/*.ts", "src/routes/**/page.tsx"]
}

duplicates

Configuration for fallow dupes:

Field	Type	Default	Description
mode	"strict" | "mild" | "weak" | "semantic"	"mild"	Detection mode. strict/mild match exact tokens. weak blinds string literal values. semantic blinds identifiers and all literal values for structural (Type-2) detection.
minTokens	number	50	Minimum token count for a code block to be considered a clone
minLines	number	5	Minimum line count for a clone group
threshold	number	0	Maximum allowed duplication percentage before failing (exit code 1). 0 disables the limit.
enabled	boolean	true	Toggle duplication detection on/off
ignore	string[]	[]	Glob patterns to exclude from duplication analysis. Merged with the built-in defaults below unless ignoreDefaults is false.
ignoreDefaults	boolean	true	Merge built-in generated-output ignores (**/.next/**, **/.nuxt/**, **/.svelte-kit/**, **/.turbo/**, **/.parcel-cache/**, **/.vite/**, **/.cache/**, **/out/**, **/storybook-static/**) with ignore. Set to false to use only your configured ignore list.
skipLocal	boolean	false	Only report cross-directory duplicates, skip file-internal clones
crossLanguage	boolean	false	Enable cross-language clone detection between .ts and .js files by stripping TypeScript type annotations
ignoreImports	boolean	false	Exclude ES import declarations from clone detection. Reduces noise from sorted import blocks that naturally look similar across files. Only affects ES import statements; CommonJS require() calls are not filtered.
normalization	object	none	Fine-grained normalization overrides: ignoreIdentifiers, ignoreStringValues, ignoreNumericValues
minCorpusSizeForShingleFilter	number	1024	Tokenized file count above which focused-mode duplication (driven by --changed-since or audit) prefilters unchanged files via k-token shingles. Below this threshold the prefilter is skipped because building the shingle index outweighs the savings.
minCorpusSizeForTokenCache	number	5000	Source file count above which the persistent duplication token cache activates under <root>/.fallow/cache/dupes-tokens-vN/. Below this threshold the cache load/save overhead exceeds the tokenize savings, so the cache stays disabled even without --no-cache.

{
  "duplicates": {
    "mode": "mild",
    "minTokens": 50,
    "minLines": 5,
    "threshold": 5,
    "ignore": ["**/*.generated.ts"],
    "skipLocal": true,
    "ignoreImports": true
  }
}

health

Configuration for fallow health:

Field	Type	Default	Description
maxCyclomatic	number	20	Maximum cyclomatic complexity before reporting
maxCognitive	number	15	Maximum cognitive complexity before reporting
maxCrap	number	30	Maximum CRAP score before reporting
crapRefactorBand	number	5	Band below maxCyclomatic where CRAP-only findings also receive a secondary refactor-function action when cognitive complexity is at least half of maxCognitive
ignore	string[]	[]	Glob patterns for files to exclude from complexity analysis
suggestInlineSuppression	boolean	true	Emit suppress-line action hints on health findings in JSON output. Auto-omitted when --baseline/--save-baseline is active regardless of this setting. Set to false to opt out across the project when you do not want CI-driven inline suppression hints.

{
  "health": {
    "maxCyclomatic": 20,
    "maxCognitive": 15,
    "maxCrap": 30,
    "crapRefactorBand": 5,
    "ignore": ["**/*.generated.ts", "src/legacy/**"],
    "suggestInlineSuppression": true
  }
}

audit

Configuration for fallow audit, the changed-file review command:

Field	Type	Default	Description
gate	"new-only" | "all"	"new-only"	Which findings affect the audit verdict. new-only fails only on issues introduced by the current changeset while keeping inherited findings visible as context. all gates every finding in changed files and skips the extra base-snapshot attribution pass.
cacheMaxAgeDays	number	30	Max age (in days since last reuse or fresh create) of a persistent reusable base-snapshot worktree cache. Older entries are reclaimed at the top of the next fallow audit. 0 disables the GC. Overridable per-run via the FALLOW_AUDIT_CACHE_MAX_AGE_DAYS env var, which wins when both are set.

{
  "audit": {
    "gate": "new-only",
    "cacheMaxAgeDays": 14
  }
}

[audit]
gate = "all"
cacheMaxAgeDays = 14

fix

Configure fallow fix behavior.

Field	Type	Default	Description
catalog.deletePrecedingComments	"auto" | "always" | "never"	"auto"	Controls contiguous YAML comment blocks immediately above removed pnpm catalog entries.

{
  "fix": {
    "catalog": {
      "deletePrecedingComments": "auto"
    }
  }
}

auto removes a leading comment block when it clearly belongs to the deleted catalog entry: the block directly follows the parent catalog: / catalogs.<name>: header, or follows a blank separator. Use always to remove every adjacent leading comment block, or never to keep leading comments in place for manual review.

Two escape hatches keep curated comments safe regardless of policy:

• Add # fallow-keep to any line in a comment block to preserve the entire block even under always. Mirrors the existing fallow-ignore-next-line / fallow-ignore-file inline-suppression convention:

  catalog:
    # fallow-keep: audit trail, CVE-2024-XXXX
    react: ^18.2.0
  

• Under auto, section-banner blocks are automatically preserved. A banner is any comment whose body (after # and optional whitespace) starts with three or more repeats of =, -, *, _, ~, +, or #:

  catalog:
    # === React 18 production pins ===
    react: ^18.2.0
  

  Under always the banner heuristic does not apply; use # fallow-keep to protect banners when running with always.

The JSON action emitted to fixes[N] carries both line (1-based first deleted line, the leading comment when auto / always absorb one) and entry_line (the catalog entry’s original 1-based line). CI annotators and dedup caches that key on the entry position should use entry_line for a stable anchor; tools that want to point at the actual file edit should use line.

production

Enable production mode to focus on code that ships to users. Accepts the legacy boolean form (applies to every analysis) or a per-analysis object so you can run, for example, production-only health while keeping dead-code and duplication on the full tree:

{
  "production": true
}

{
  "production": {
    "deadCode": false,
    "health": true,
    "dupes": false
  }
}

The CLI flags --production, --production-dead-code, --production-health, and --production-dupes (bare combined runs and fallow audit) override config. The matching env vars FALLOW_PRODUCTION, FALLOW_PRODUCTION_DEAD_CODE, FALLOW_PRODUCTION_HEALTH, FALLOW_PRODUCTION_DUPES follow the same precedence ladder, with per-analysis env beating global env. See global flags for the full ladder.

workspaces

Additional workspace patterns beyond what’s detected from package.json or pnpm-workspace.yaml:

{
  "workspaces": {
    "patterns": ["tools/*", "shared/*"]
  }
}

extends

Inherit from one or more base config files. Handy for sharing config across projects or keeping a base config with per-project overrides.

{
  "extends": ["./configs/base.json", "./configs/strict.json"]
}

extends = ["./configs/base.json", "./configs/strict.toml"]

The extends field supports three source types:

Source	Example	Description
Relative path	"./configs/base.json"	Local file, resolved relative to the config file
npm package	"npm:@my-org/fallow-config"	Reads the package’s main entry from node_modules
HTTPS URL	"https://example.com/fallow-base.json"	Fetched remotely over HTTPS

{
  "extends": [
    "./configs/local-overrides.json",
    "npm:@my-org/fallow-config",
    "https://example.com/shared/fallow-base.json"
  ]
}

Key behaviors:

• Deep merge: Object fields (like rules) are deep-merged. The child config overrides 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.

URL extends

URL sources must use https:// (plain HTTP is rejected). Fallow fetches the config on every run with no caching.

• Timeout: 5 seconds by default, configurable via FALLOW_EXTENDS_TIMEOUT_SECS
• Body limit: 1 MB maximum response size
• Chaining: A URL-sourced config can extend other URLs or npm: packages, but not relative paths (there is no filesystem context to resolve against)

URL extends fetch on every run. If the remote server is slow or unavailable, your analysis will fail. Pin critical shared configs to a versioned URL or use npm: packages for reliability.

overrides

Apply different rules to specific file patterns. For example, relax rules in test files or tighten 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.

sealed

Mark a config as sealed to guarantee it cannot be modified by ancestor configs being injected via extends. When sealed: true:

• extends paths must be file-relative
• extends paths must resolve within the config’s own directory (no ../ escapes)
• npm: and https: extends are rejected with a clear error

{
  "sealed": true,
  "extends": ["./base.json"]
}

sealed = true
extends = ["./base.json"]

Use cases:

• Library publishers shipping a .fallowrc.json as part of an npm package can guarantee the config is self-contained
• Monorepo sub-packages (e.g., a shared component library used by multiple apps) that intentionally do not inherit from the monorepo root config

sealed: true does not affect config discovery. Fallow’s first-match-wins walk already stops at the nearest config in the directory tree. This option only constrains what extends can reference.

boundaries

Define architecture boundary zones and import rules. Use a built-in preset or define custom zones.

{
  "boundaries": {
    "preset": "bulletproof"
  }
}

Available presets: layered, hexagonal, feature-sliced, bulletproof. Or define custom zones and rules for full control.

See Architecture boundaries for presets, custom zones, examples, and output formats.

rules

Per-issue-type severity rules: error (default, fails CI with exit code 1), warn (reports but exits 0), or off (skip detection entirely).

{
  "rules": {
    "unused-files": "warn",
    "unused-exports": "error",
    "circular-dependency": "off"
  }
}

See Rules and severity for the full list of issue types, including pnpm catalog hygiene such as unused-catalog-entries and empty-catalog-groups, default severities, and per-glob overrides via the overrides field.

flags

Customize feature flag detection. Add SDK call patterns beyond the built-ins (LaunchDarkly, Statsig, Unleash, GrowthBook, Split, PostHog, Vercel Flags, ConfigCat, Flagsmith, Optimizely, Eppo), declare environment variable prefixes, or enable opt-in heuristic detection.

Field	Type	Default	Description
sdkPatterns	SdkPattern[]	[]	Additional SDK call patterns to detect as feature flags. Merged with built-ins. Each entry: function (function name to match), nameArg (zero-based index of the argument containing the flag name, default 0), provider (optional label shown in output).
envPrefixes	string[]	[]	Environment variable prefixes that indicate feature flags. Merged with built-ins. Only process.env.* accesses matching these prefixes are reported.
configObjectHeuristics	boolean	false	Enable heuristic detection: property accesses on objects whose name contains “feature”, “flag”, or “toggle” are reported as low-confidence flags. Opt-in due to higher false-positive rate.

{
  "flags": {
    "sdkPatterns": [
      { "function": "useFlag", "nameArg": 0, "provider": "LaunchDarkly" },
      { "function": "client.getFeatureValue", "nameArg": 0 }
    ],
    "envPrefixes": ["FEATURE_", "NEXT_PUBLIC_ENABLE_"],
    "configObjectHeuristics": false
  }
}

See fallow flags for the command that consumes this configuration.

resolve

Module resolver configuration. Controls how fallow matches package.json exports and imports maps.

Field	Type	Default	Description
conditions	string[]	[]	Additional export / import condition names to honor during resolution. Merged with fallow’s built-in set: development, import, require, default, types, node (plus react-native and browser when the React Native or Expo plugin is active). User conditions are matched with higher priority than the baseline.

Use this to honor community-defined conditions like worker, edge-light, deno, or any custom condition your bundler uses. The built-in development condition already ships in the baseline, so packages that declare a development branch (common in monorepos where development points at source and import points at compiled output) resolve to source without any config.

{
  "resolve": {
    "conditions": ["worker", "edge-light"]
  }
}

With this config, a package.json like:

{
  "exports": {
    "./api": {
      "worker": "./src/api.worker.ts",
      "import": "./dist/api.js"
    }
  }
}

resolves ./api to src/api.worker.ts instead of dist/api.js.

See the Node.js community conditions reference for the full list of established condition names.

codeowners

Path to a CODEOWNERS file for --group-by owner. When unset, fallow auto-probes CODEOWNERS, .github/CODEOWNERS, .gitlab/CODEOWNERS, and docs/CODEOWNERS. Set this to use a non-standard location.

{
  "codeowners": ".github/CODEOWNERS"
}

framework

Inline framework plugin definitions. Define custom entry points, ignored files, or test patterns without a separate plugin file.

{
  "framework": [
    {
      "name": "my-framework",
      "entry": ["src/server.ts"],
      "ignore": ["**/*.internal.ts"]
    }
  ]
}

plugins

Paths to external plugin files or directories. In addition to these explicit paths, fallow automatically discovers *.toml, *.json, *.jsonc files in .fallow/plugins/ and fallow-plugin-*.{toml,json,jsonc} in the project root.

{
  "plugins": ["./my-plugins/custom.toml", "./plugins/"]
}

cache

Incremental cache tuning. Today the only knob is maxSizeMb, which caps the on-disk extraction cache and triggers LRU eviction during save.

{
  "cache": {
    "maxSizeMb": 64
  }
}

Default cap: 256 MB. The cap is the size of the serialized .fallow/cache.bin; saves that cross 80% of the cap evict the oldest entries down to 60%. The env var FALLOW_CACHE_MAX_SIZE overrides this field when both are set. Both values are interpreted as whole megabytes.

The cache invalidates automatically when extraction-affecting config changes (currently: active plugin names + inline framework definition names). Detection-only fields (entry, ignorePatterns, severity overrides) do not bust the cache. See ADR-009 for the contract.

--no-cache disables the cache entirely; this section is then irrelevant.

regression

Regression detection baseline embedded in config. Stores issue counts from a known-good state for CI regression checks. Populated by --save-regression-baseline (no path argument), read by --fail-on-regression.

{
  "regression": {
    "baseline": {
      "unused_files": 11,
      "unused_exports": 48,
      "unused_types": 5,
      "unused_dependencies": 3,
      "circular_dependencies": 1
    }
  }
}

ignorePatterns excludes files entirely from analysis. If you only want to suppress specific exports, use ignoreExports instead.

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.