Migrating from knip

Move from knip to fallow: one command converts your knip config to a fallow config. Learn what gets migrated and what to check after the move.

The fallow migrate command translates your knip configuration to a fallow config. This page shows the steps, the field mapping, and the settings that need a manual check.

Migration workflow

1. 1

   Preview the migration

   Run fallow migrate --dry-run to see the generated config. The command writes no files.

   fallow migrate --dry-run

   fallow looks for knip.json, knip.jsonc, .knip.json, .knip.jsonc, knip.ts, knip.config.ts, and the knip field in package.json. Fallow detects the TypeScript config files (knip.ts, knip.config.ts) but cannot parse them. Convert them to knip.json first.

   {
     "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
     // Migrated from knip.json
     "entry": [
       "src/index.ts",
       "src/cli.ts"
     ],
     "ignoreFindings": [
       "**/*.generated.ts"
     ],
     "ignoreDependencies": [
       "@types/node"
     ]
   }
   
   Migrated from: knip.json
   
   Warning (1):
     [knip] `ignoreBinaries`: Binary filtering is not configurable in fallow
   
   Note: knip and fallow use different glob engines; verify migrated entry /
   ignoreFindings with `fallow dead-code` before relying on CI.
   https://fallow.tools/docs/migration/from-knip/
   
   Note: knip's ignore also suppresses dependency and manifest issues by file
   path; fallow's ignoreFindings never hides manifest-owned findings such as
   unused dependencies.
   https://fallow.tools/docs/migration/from-knip/

2. 2

   Generate the config

   When the preview looks correct, run the migration:

   fallow migrate            # Write .fallowrc.json
   fallow migrate --toml     # Or output as fallow.toml

3. 3

   Review the config

   Open the generated config. Check the translated entry points, ignore patterns, and plugin mappings. Fallow shows a warning for each field that it could not migrate automatically.

4. 4

   Run your first analysis

   Run the dead code analysis and examine the findings. Then run the other analyses:

   fallow dead-code    # Unused code + circular deps + boundaries
   fallow dupes        # Code duplication
   fallow health       # Complexity hotspots + maintainability scores
   fallow              # All of the above in one pass

What gets migrated

Warnings and caveats

fallow migrate warns about each setting that it cannot translate, so you do not lose a setting without notice.

Unknown rule names. Your knip rules, exclude, or include entries can reference a key that fallow does not know. The cause can be a typo, a future knip rule, or an issue type that the migrator does not know yet. The migration then prints a warning like this one:

Warning (1):
  [knip] `rules.unsued-files`: unknown knip issue type `unsued-files`; not migrated (suggestion: check for a typo or report the missing mapping at https://fallow.tools/docs/migration/from-knip/)

Some keys are on the documented list of keys that cannot be mapped: binaries, optionalPeerDependencies, and similar issue types that knip reports and fallow does not. For these keys, the warning reads issue type \X` has no fallow equivalent` and has no suggestion.

Glob-engine drift. knip and fallow use different glob engines. The migration copies entry and ignoreFindings verbatim, but they can match a slightly different set of files than in knip. When the migrated config has either field, the migrate command prints:

Note: knip and fallow use different glob engines; verify migrated entry /
ignoreFindings with `fallow dead-code` before relying on CI.
https://fallow.tools/docs/migration/from-knip/

Common patterns (brace expansion {ts,tsx}, double-star **, src/**) match the same files in both engines. ignoreFindings keeps a leading ! as an exception to the earlier patterns. Run fallow dead-code on a representative subset before you use the migrated globs in CI.

Dependency regexes. knip reads an ignoreDependencies entry as a regex when it contains one of * + \ ( | { ^ $. Fallow reads ignoreDependencies entries as exact names or as globs, see ignoreDependencies. The migration converts a regex to a glob only when the glob matches exactly the same package names:

A regex that has no exact glob form stays out of the config, for example an alternation such as ^(react|vue)$, a character class such as ^@acme/[a-z]+$, or .+ in the middle of a name. The migration prints a warning for each such entry:

Warning (1):
  [knip] `ignoreDependencies`: regex pattern `^(react|vue)$` skipped (no glob matches the same packages) (suggestion: rewrite it as a glob such as `@scope/*`, or add each dependency name)

Add the skipped entries by hand as globs or as exact names. After the migration, fallow dead-code names every ignoreDependencies glob that matches no declared dependency, so a glob with a typo does not go unnoticed. See Unmatched config patterns.

Ignore scope. knip's ignore also hides dependency and manifest issues by file path. Fallow's ignoreFindings never hides manifest-owned findings, such as unused dependencies. The migrate command prints a note about this difference for every knip migration.

See also