Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fallow.tools/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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": [
    { "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

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"]
}
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:
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 (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.
Glob patterns for files to exclude from analysis entirely.
{
  "ignorePatterns": ["**/*.generated.ts", "**/*.d.ts", "legacy/**"]
}
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"]
}
Rules for ignoring specific exports. Useful for public API packages.
{
  "ignoreExports": [
    { "file": "src/index.ts", "exports": ["*"] },
    { "file": "src/utils/*.ts", "exports": ["default"] }
  ]
}
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.
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.
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.
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"]
}
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"]
}
Configuration for fallow dupes:
FieldTypeDefaultDescription
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.
minTokensnumber50Minimum token count for a code block to be considered a clone
minLinesnumber5Minimum line count for a clone group
thresholdnumber0Maximum allowed duplication percentage before failing (exit code 1). 0 disables the limit.
enabledbooleantrueToggle duplication detection on/off
ignorestring[][]Glob patterns to exclude from duplication analysis. Merged with the built-in defaults below unless ignoreDefaults is false.
ignoreDefaultsbooleantrueMerge 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.
skipLocalbooleanfalseOnly report cross-directory duplicates, skip file-internal clones
crossLanguagebooleanfalseEnable cross-language clone detection between .ts and .js files by stripping TypeScript type annotations
ignoreImportsbooleanfalseExclude 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.
normalizationobjectnoneFine-grained normalization overrides: ignoreIdentifiers, ignoreStringValues, ignoreNumericValues
minCorpusSizeForShingleFilternumber1024Tokenized 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.
minCorpusSizeForTokenCachenumber5000Source 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
  }
}
Configuration for fallow health:
FieldTypeDefaultDescription
maxCyclomaticnumber20Maximum cyclomatic complexity before reporting
maxCognitivenumber15Maximum cognitive complexity before reporting
maxCrapnumber30Maximum CRAP score before reporting
ignorestring[][]Glob patterns for files to exclude from complexity analysis
suggestInlineSuppressionbooleantrueEmit 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,
    "ignore": ["**/*.generated.ts", "src/legacy/**"],
    "suggestInlineSuppression": true
  }
}
Configuration for fallow audit, the changed-file review command:
FieldTypeDefaultDescription
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.
{
  "audit": {
    "gate": "new-only"
  }
}

[audit]
gate = "all"
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.
Additional workspace patterns beyond what’s detected from package.json or pnpm-workspace.yaml:
{
  "workspaces": {
    "patterns": ["tools/*", "shared/*"]
  }
}
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:
SourceExampleDescription
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.
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.
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.
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.
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, default severities, and per-glob overrides via the overrides field.
Customize feature flag detection. Add SDK call patterns beyond the built-ins (LaunchDarkly, Statsig, Unleash, GrowthBook), declare environment variable prefixes, or enable opt-in heuristic detection.
FieldTypeDefaultDescription
sdkPatternsSdkPattern[][]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).
envPrefixesstring[][]Environment variable prefixes that indicate feature flags. Merged with built-ins. Only process.env.* accesses matching these prefixes are reported.
configObjectHeuristicsbooleanfalseEnable 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.
Module resolver configuration. Controls how fallow matches package.json exports and imports maps.
FieldTypeDefaultDescription
conditionsstring[][]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.
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"
}
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"]
    }
  ]
}
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/"]
}
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.