Remove unused code with fallow fix
Preview, review, apply and verify the changes of fallow fix, which removes unused exports and unused dependencies.
The report of the demo project lists three unused exports in three files and one unused dependency in package.json. You can remove each one by hand. In a real project, the list often has hundreds of lines, and each edit is the same small change. At the end of this guide, fallow fix has removed the unused exports and unused dependencies of your project, and your tests still pass.
Before you start
- Commit or stash your work. Then
git diffshows only the changes offallow fix, andgit checkout .undoes them. - Run
fallow dead-codeand read the findings. Each change offallow fixcomes from one finding. - Correct the false positives first, because a wrong finding gives a wrong fix. Fix a false positive shows how.
What fallow fix changes
For each fixable finding, fallow fix makes the smallest change that removes it:
| Finding | Change |
|---|---|
| Unused export | Fallow removes the export keyword. The declaration stays in the file. |
Unused dependency, also in devDependencies and optionalDependencies | Fallow removes the line from package.json. |
| Unused enum member | Fallow removes the member from the enum. |
| Unused pnpm catalog entry | Fallow removes the entry from pnpm-workspace.yaml. |
| Duplicate export | Fallow adds an ignoreExports rule to your config file. When no config file exists, fallow creates .fallowrc.json. |
fallow fix never deletes a file. It never removes a function body, and it does not add an unlisted dependency to package.json. Delete an unused file yourself.
An exported enum that the file does not use is an exception: fallow removes the whole declaration. A class member is removed only when the type-aware analysis proves that no code uses it.
The issue types reference lists each issue type, and its rule page tells you if the type is fixable.
Steps
1. Preview the changes
npx fallow fix --dry-run
Would remove export from src/services/orders.ts:18 `cancelOrder`
Would remove export from src/lib/format.ts:3 `formatPercent`
Would remove export from src/lib/index.ts:1 `formatPercent`
Would remove `left-pad` from dependencies in package.json
Dry run complete. No files were modified.
A dry run changes no file, so you can run it again after each change of the config.
2. Review each line
The dry run shows what fallow wants to change. Before you accept it, ask one question for each line: can code that fallow does not see use this name or this package? Examples are a script outside the repository, a test that loads a file by path, or a package that the runtime loads without an import.
When the answer is yes, do not apply the fix. Tell fallow about the use, and run the dry run again. Find why fallow reports a finding shows where fallow looked.
3. Apply the changes
When each line of the preview is correct, apply the changes:
npx fallow fix
In a terminal, fallow asks for a confirmation. A script, a CI job or an agent has no terminal, so add --yes there:
npx fallow fix --yes
Fixed 4 issue(s).
Without --yes, a run without a terminal stops with exit code 2 and changes no file:
Error: fix command requires --yes (or --force) in non-interactive environments. Use --dry-run to preview changes first, then pass --yes to confirm.
hint: Run `fallow fix --dry-run` and review the preview, then pass --yes to apply the approved changes.
4. Read the diff
Fallow edited your files, so read each change as you read the change of a colleague:
git diff
In src/services/orders.ts, cancelOrder loses its export keyword:
-export const cancelOrder = (order: Order): Order => ({ ...order, quantity: 0 });
+const cancelOrder = (order: Order): Order => ({ ...order, quantity: 0 });
The barrel file src/lib/index.ts stops passing on formatPercent, and src/lib/format.ts loses the export keyword of the same function:
-export { formatPrice, formatPercent } from "./format";
+export { formatPrice } from "./format";
In package.json, the left-pad line is gone:
"dependencies": {
- "zod": "^3.23.8",
- "left-pad": "^1.3.0"
+ "zod": "^3.23.8"
},
After the fix, cancelOrder is a local function that no code calls. Fallow does not report unused local code, so delete it yourself, or let your linter find it.
5. Build and test
The diff looks right, and the build and the tests prove it:
npm run build && npm test
After a dependency removal, also run npm install (or the install command of your package manager) to update the lockfile.
Fix from a script or an agent
A script cannot answer a prompt, and it cannot review prose, so it uses the JSON output for both steps:
npx fallow fix --dry-run --format json --quiet
{"dry_run":true,"fixes":[{"type":"remove_export","path":"src/services/orders.ts","line":18,"name":"cancelOrder"},{"type":"remove_export","path":"src/lib/format.ts","line":3,"name":"formatPercent"},{"type":"remove_export","path":"src/lib/index.ts","line":1,"name":"formatPercent"},{"type":"remove_dependency","package":"left-pad","location":"dependencies","file":"package.json"}],"total_fixed":0,"skipped":0,"skipped_content_changed":0,"skipped_mixed_line_endings":0,"skipped_low_confidence_exports":0,"skipped_low_confidence_dependencies":0,"skipped_low_confidence_members":0,"skipped_kept_re_exports":0,"skipped_shared_declarations":0}
The script checks the fixes array. When it accepts the changes, it runs:
npx fallow fix --yes --format json --quiet
A script can also decide before the dry run. In the JSON output of fallow dead-code, each finding has an actions array. An action with auto_fixable: true is a change that fallow fix makes. The value can differ between two findings of the same issue type. fallow fix describes the output fields.
Check the result
Run the analysis again:
npx fallow dead-code
● Unused files (1)
src/utils/legacy-currency.ts
Files not reachable from any entry point
https://fallow.tools/docs/explanations/dead-code/#unused-files
● Unlisted dependencies (1)
uuid
Packages imported in code but missing from package.json
https://fallow.tools/docs/explanations/dead-code/#unlisted-dependencies
✗ 1 file · 1 unlisted dependency (0.03s)
The unused exports and the unused dependency are gone. The unused file and the unlisted dependency stay, because fallow fix does not change them: delete src/utils/legacy-currency.ts, and add uuid to package.json.
If it fails
| Problem | Cause | Fix |
|---|---|---|
| The dry run lists fewer changes than the report has findings. | Fallow does not change a file in a directory such as __mocks__, fixtures, e2e or examples, or a file with an unresolved import. It also skips a finding when some files did not parse. | Fix the unresolved import or the parse error, and run the dry run again. Change the other files by hand. |
skipped_content_changed is above 0. | A file changed between the analysis and the write. | Run fallow fix again. |
| The build fails after the fix. | Code that fallow did not see used a removed export. | Undo the change with Git. Tell fallow about the use, for example with entry. |
| A duplicate export is not fixed in a monorepo. | Fallow does not create a config file inside one package. | Run fallow fix from the root of the workspace. |
Related
- Next: Suppress a finding. Use it for a finding that you keep on purpose.
fallow fix: each option, the JSON output and the exit codes.- Dead code: what fallow reports and how it decides.