Config: files and entry points
Find the fallow config keys for files and entry points, with type, default, allowed values and description.
The config file holds the settings of fallow. How config works explains where fallow finds the file and how files merge.
$schema
- Type:
string(optional)
A string pointing at fallow's JSON Schema URL, used only by editors for autocomplete and validation of the config file; it has no effect on analysis, and fallow does not write it back when it saves a config. Set it to ./node_modules/fallow/schema.json for npm installs (version-aligned, offline, avoids VS Code's untrusted-remote-schema prompt), or https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json for non-npm installs; any other value is ignored by fallow.
minimumVersion
- Type:
string(optional)
The lowest fallow version this config is written for, as MAJOR.MINOR.PATCH. An older binary stops with a message naming both versions instead of failing on the first field it does not recognize, so a config committed to a shared repository says which upgrade it needs rather than reading like a typo. Optional and unset by default; set it in the same change that adds a field introduced in a newer version. Only digits are accepted: a pre-release suffix such as -beta.1 is a config error. A parent config of extends can set it too. It gates nothing on its own: an unknown key still fails on a binary at or above this version, because there the key really is a typo.
extends
- Type:
string or string[]
A single parent config source, or an ordered array of them, to inherit before this file's own keys apply; each source is a file-relative path, an npm:<package> specifier, or an https:// URL (http:// is rejected), deep-merged in order so objects merge field-by-field while arrays and scalars in this file replace the parent's, with a cycle guard and a depth limit of 10 levels. An https:// source loads only with --allow-remote-extends; fallow waits 5 seconds for it (FALLOW_EXTENDS_TIMEOUT_SECS changes this) and refuses a response over 1 MB. Set it to share a base config across a monorepo or team; fallow reads it at load and does not write it back when it saves a config.
entry
- Type:
string[] - Default:
[]
An array of project-root-relative glob patterns whose matching files are seeded as manual entry points, on top of the framework and package.json entries fallow discovers automatically, so their transitive imports are not reported as unused. Set it (e.g. ["src/main.ts"]) when a file is a real runtime root that no plugin or manifest declares; patterns are validated at load and matched against discovered files. For a script that does not run in production, use supportEntry and leave its glob out of entry: a file that also matches entry stays a runtime root. A single * stays within one path segment; use ** to match across directories.
ignorePatterns
- Type:
string[] - Default:
[]
An array of project-root-relative glob patterns for files to exclude from analysis entirely; entries are unioned with fallow's built-in defaults (**/node_modules/**, **/dist/**, **/build/**, **/.git/**, **/coverage/**, **/*.min.js, **/*.min.mjs, **/*.min.cjs, **/*.bundle.js), so custom globs add to rather than replace them. Set it (e.g. ["generated/**"]) to drop generated or vendored trees from every detector; patterns are validated at load. A !-prefixed entry is an exception that applies after the defaults and the positive patterns: "!src/policy/coverage/**" brings back hand-written source under a built-in default such as **/coverage/**, and "!.config/**" adds a hidden directory to discovery. Paths under node_modules or .git can not be lifted, and a ! entry that names one of these segments is a config error. A single * stays within one path segment; use ** to match across directories.
supportEntry
- Type:
string[] - Default:
[]
An array of project-root-relative glob patterns whose matching files are support entry points: dev scripts, tooling and setup files that run outside production. In default mode a support entry keeps its file and its imports reachable, the same as entry. In --production mode (or production for dead-code analysis), fallow leaves a file that only a support entry matches out of the analysis, so its imports credit no export, file or dependency. A file that also matches entry, a framework plugin or a package.json field stays an entry point, and a support file that production code imports stays a normal module. Use entry for the files that run in production. A single * stays within one path segment; use ** to match across directories.
resolve
- Type:
object
Configures the module resolver. Its one key conditions is a list of additional package.json exports/imports condition names to honor, matched at higher priority than fallow's built-ins (development, import, require, default, types, node, plus react-native/browser when the React Native or Expo plugin is active). Set it when a package's exports map has custom branches (e.g. worker, deno, edge) that fallow should follow instead of the default branch.
| Key | Type | Default |
|---|---|---|
conditions | string[] |
resolve.conditions
- Type:
string[]
Additional export/import condition names to honor during module resolution. Merged with fallow's built-in conditions (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, so a package.json exports entry like:
{ "./api": { "worker": "./src/api.worker.ts", "import": "./dist/api.js" } }
resolves to the worker branch when "worker" is listed here.
The community conditions of Node.js list the conditions that tools define.
production
- Type:
boolean or object
Enables production mode, which excludes test/spec/story/dev files from discovery and forces unused-dev-dependencies and unused-optional-dependencies to off. Accepts a boolean (default false) applied to all analyses, or a per-analysis object { deadCode?, health?, dupes?, ignore? } that scopes production mode to individual analyses: deadCode applies to fallow dead-code, health to fallow health and dupes to fallow dupes, and each applies to its part of combined fallow and fallow audit (each analysis key a boolean, default false). The object key ignore is a glob array of extra paths that discovery drops in production mode only. Set it to analyze only shipped code; the --production/--no-production and --production-{dead-code,health,dupes} CLI flags and FALLOW_PRODUCTION* env vars override this value (CLI flags win, then per-analysis env, then global env, then config).
production.deadCode
- Type:
boolean - Default:
false
When production is a per-analysis object, enables production mode for dead-code analysis only (boolean, default false): unused-files/exports/dependencies detection excludes test/spec/story/dev files and forces unused-dev-dependencies/unused-optional-dependencies to off, while health and dupes stay on the full tree. Set it to scope production analysis to dead code independently.
production.health
- Type:
boolean - Default:
false
When production is a per-analysis object, enables production mode for the health/complexity analysis only (boolean, default false), so fallow health in combined fallow and fallow audit scores only shipped code (test/spec/story/dev files excluded) while dead-code and dupes stay on the full tree. Set it to scope production analysis to health independently.
production.dupes
- Type:
boolean - Default:
false
When production is a per-analysis object, enables production mode for duplication analysis only (boolean, default false), so clone detection runs on shipped code only (test/spec/story/dev files excluded) while dead-code and health stay on the full tree. Set it to scope production analysis to dupes independently.
production.ignore
- Type:
string[]
When production is a per-analysis object, an array of project-root-relative glob patterns for paths that discovery drops in production mode only, in addition to the built-in test/spec/story/dev patterns (default empty). The default run keeps these paths. The globs apply to each analysis that runs in production mode, also when the --production flag or a FALLOW_PRODUCTION* env var selects the mode. Set it for tooling, CI scripts, seeds and test harnesses that never ship (e.g. ["scripts/**"]). A single * stays within one path segment; use ** to match across directories.
dynamicallyLoaded
- Type:
string[] - Default:
[]
An array of project-root-relative glob patterns for files loaded at runtime by a mechanism the static graph cannot see (dynamic path resolution, config-driven loading); matching files are seeded as entry points so they and their imports stay reachable. Empty by default; set it (e.g. ["plugins/**/*.ts", "locales/**/*.json"]) for plugin or locale trees pulled in dynamically. A single * stays within one path segment; use ** to match across directories.
markupExtensions
- Type:
string[] - Default:
[]
An array of file extensions, without the leading dot, for server-side template files whose text counts as CSS class references for the unreferenced-css-class finding of fallow health --css. These files are read as text only: they do not join source discovery or the module graph, so they never become unused files and their imports are not followed. Templates are more lenient than Markdown: the whole text of a template file counts as a dynamic class reference, so any class-like word in it counts as used, also a common word such as hidden or title in prose or a template tag. A Markdown file joins the reference text only when it has dynamic class syntax. The extensions liquid, njk, hbs, handlebars, twig, and blade.php are always read; set this (e.g. ["tpl", "erb"]) for other template languages. An extension matches the end of a file name, ignoring case, so blade.php matches welcome.blade.php. Values may contain only letters, digits, ., -, and _. A value whose last segment is a script, stylesheet, data or asset extension (js, ts, css, json, svg, xml, map, and similar, so also module.css or d.ts), or a compound value that ends in a markup extension that fallow already reads (page.html), is a config error. The walk uses the ignore files of source discovery (.gitignore, .ignore), skips ignorePatterns, health.ignore, node_modules, vendor, and build output directories, reads only regular files, and skips files over the --max-file-size limit. In extends, a child list replaces the parent list.
codeowners
- Type:
string(optional)
A project-root-relative path to a CODEOWNERS file, used by fallow health --hotspots --ownership to attribute declared owners and compute unowned/drifting ownership state; setting it overrides the default probe order (CODEOWNERS, .github/CODEOWNERS, .gitlab/CODEOWNERS, docs/CODEOWNERS). String, defaults to null (auto-probe the standard locations); set it only when the CODEOWNERS file lives at a non-standard location.
publicPackages
- Type:
string[] - Default:
[]
An array of internal workspace package names (or globs matched against workspace package names) whose public API is intentionally consumed outside the analyzed graph; their entry points and re-export surface become reachability roots, so their exported files, exports, and class members are not reported as unused. Set it (e.g. ["@myorg/shared-lib", "@myorg/*"]) for library packages in a monorepo that ship an API to external consumers; only meaningful when workspaces are present (an empty list or no workspaces is a no-op).
sealed
- Type:
boolean - Default:
false
When true, restricts this config's extends entries to file-relative paths that resolve inside the config file's own directory; any https:// URL, npm: package, or relative path escaping that directory is rejected at load with a hard error. Boolean, defaults to false (URL, npm, and any-relative extends are permitted); set it to true to harden a config against pulling in remote or out-of-tree bases.
includeEntryExports
- Type:
boolean - Default:
false
When true, fallow checks the exports of every entry-point file for unused exports. When false, fallow credits all exports of an entry file as used, unless a plugin usedExports rule matches the file: then fallow checks the other exports of that file, so a stray export in a framework route (e.g. meatdata for metadata) is flagged without this setting. The setting extends the check to package entries and other entry files that no plugin rule matches; the names in plugin usedExports lists stay credited. Boolean, defaults to false; the CLI flag --include-entry-exports applies the same behavior for one run.
autoImports
- Type:
boolean - Default:
false
When true, drops Nuxt convention-based entry-pattern fallbacks so genuinely-unreferenced convention files surface as unused-file. Component fallbacks are kept when nuxt.config customizes components: in a way fallow does not model, and composable/util fallbacks are kept when it customizes imports:; a config that scans no more than the Nuxt defaults (components: false, components: [], components: { dirs: [] }, components: true, imports: { scan: false }, imports: {}, imports: { dirs: [] }) is treated like the default and its fallbacks are dropped; imports: { autoImport: false } on its own is not, because it only switches the injection off while the same directories stay registered behind #imports. A nuxt.config that carries any top-level key fallow cannot read statically, a computed key, an accessor, or a spread such as { ...base, devtools: {} }, keeps both surfaces' fallbacks for that root, because the spread may hold the keys that decide. Only top-level keys count when the config object is readable: a nested key such as a routeRules path ending in components does not keep a fallback. Nested components or imports keys in $production, $development, $test or $env.<name>, and components or imports hooks (a components:* key or a nested components object in hooks, also inside those overrides), count as that surface's key; such an override object or hooks object that fallow cannot read statically falls back to a text match for the keys. Each root is classified on its own config plus the configs of its local layers, so one custom nuxt.config in a monorepo does not keep every other workspace's fallbacks. A local layer is a directory named in extends, or a layers/<name> directory, that holds a nuxt.config; its convention files are entry points with the flag off and auto-import sources with it on, and #layers/<name>/ resolves to it by its $meta.name (a layers/<name> directory without one uses its directory name). A remote or package layer is only a dependency reference. Component names follow Nuxt: a component under components/global or components/islands is named after its own directory (components/global/Foo.vue is <Foo>), and .client, .server, .global and .island suffixes are stripped. A name imported or re-exported by hand from #components or #imports credits its convention file just like a template tag or a bare call; a namespace import names nothing and credits nothing. Boolean, defaults to false; set it for a Nuxt project that has explicitly configured its auto-import directories. Synthesis of auto-import graph edges (resolving <Card /> or useUserStore() to their convention files) happens regardless of this flag.
failOnParseError
- Type:
boolean - Default:
false
When true, the run fails with exit code 1 if fallow could not parse a source file cleanly (a source-parse-degraded or source-nesting-too-deep entry in workspace_diagnostics[]), and the parse-error entry of gate_outcomes names each such file. Boolean, defaults to false, so a file the parser rejects only warns. Applies to fallow dead-code, fallow health, fallow audit and the bare fallow run; the CLI flag --fail-on-parse-error arms the same gate for one run. Older fallow versions reject this key as unknown, so pair it with minimumVersion set to the release that added it.
cache
- Type:
object
Overrides the location and size ceiling of fallow's persistent extraction cache (default .fallow/cache.bin under the project root). Set to relocate the cache or cap its footprint; the object holds dir (cache directory, relative paths resolve from the project root) and maxSizeMb (extraction-cache size limit in megabytes). The FALLOW_CACHE_MAX_SIZE environment variable overrides maxSizeMb.
cache.dir
- Type:
string(optional)
Directory for fallow's persistent analysis cache. Relative paths resolve from the project root. The directory must be inside the project: an absolute path or a path that leaves the root is ignored with a warning. Use FALLOW_CACHE_DIR to put the cache outside the project.
cache.maxSizeMb
- Type:
integer(optional) - Default:
256
Maximum size of the persistent extraction cache, in megabytes. Default 256.