DEV Community

Olawale Afuye
Olawale Afuye

Posted on

Your TypeScript Codebase Is Lying to You. Fallow Will Tell You the Truth.

You think your codebase is clean.

You're wrong.

Somewhere in that repo right now, there are files nobody imports. Functions nobody calls. CSS classes nobody renders. Logic that was copy-pasted three times across different modules because someone was in a hurry and nobody ever went back.

Nobody went back.

And you've been shipping on top of that mess, quietly, every sprint.

I'm not here to judge. I've seen it at every scale — scrappy startups, enterprise platforms, well-funded teams with senior engineers. The mess is universal. What isn't universal is the tool that actually shows it to you.

That tool is Fallow.

What Fallow Actually Is

Fallow is a static + runtime code intelligence CLI for TypeScript and JavaScript projects.

One command. Three reports. No excuses left.

npx fallow
Enter fullscreen mode Exit fullscreen mode

That's it. No config file needed to start. No ceremony.

It gives you:

  • Dead Code — unused files, exports, dependencies, circular imports
  • Duplication — code clones, copy-paste instances, semantic repeats
  • Health — cyclomatic complexity, cognitive complexity, test coverage risk

Think of it as a colonoscopy for your codebase. Uncomfortable to look at. Absolutely necessary.

Why Your Current Setup Is Not Enough

ESLint is not doing this job. TypeScript is not doing this job.

ESLint catches style violations and obvious anti-patterns. It does not tell you that src/utils/formatDate.ts hasn't been imported by anything in eight months.

TypeScript's compiler will let you export a function to the void forever, completely unbothered.

These tools are not designed to answer the question: "Is this code actually alive?"

Fallow is designed for exactly that.

The Three Reports, Explained Simply

#1. Dead Code Analysis

Dead code is not just unused variables. Fallow goes deeper.

It traces your entry points — what your app actually boots from — and maps every import chain outward. Anything not reachable from that graph is dead.

This includes:

  • Unused files (the whole file. Gone. Pointless.)
  • Unused exports (the function exists. Nobody calls it.)
  • Unused dependencies (you installed it. You're not using it.)
  • Circular imports (A imports B imports A. A disaster waiting to become a bug.)

The goal here is zero. Not "few." Zero.

If something is genuinely a public API that external consumers use, you annotate it:

/** @public */
export function myPublicUtil() { ... }
Enter fullscreen mode Exit fullscreen mode

Everything else that Fallow flags? Remove it or explain yourself.

#2. Duplication Analysis

Here's the threshold that matters:

  • < 5% duplication — Low. You're doing well.
  • 5–15% — Moderate. Review it.
  • > 15% — High. You have a copy-paste culture problem, not a code problem.

Fallow finds Type-1 clones (exact copies) and Type-2 clones (same logic, renamed variables). The semantic mode catches the sneaky ones — the ones where someone changed user to customer and called it "abstraction."

When you find a clone group with 3+ instances, that's not duplication anymore. That's a bug factory. Every time the logic needs to change, someone will update two of the three copies and miss the third.

Extract it. Make it a shared utility. Move on.

#3. Health Analysis

This is where Fallow earns its keep for senior engineers.

Three metrics to know:

Cyclomatic Complexity — the number of independent paths through a function. If it's above 20, your function is doing too much. Above 50? That function should be arrested.

Cognitive Complexity — how hard the function is to read, not just test. Target: ≤15. This is the one that catches deeply nested ifs-inside-loops-inside-ternaries.

CRAP Score (Change Risk Anti-Patterns) — combines complexity with test coverage. A CRAP score above 30 means you have complex, untested code. Above 100? That module is a liability.

The fix is either: write tests, or simplify the function. Usually both.

How to Actually Start (Don't Skip This Part)

Most developers install a tool, run it once, see 400 errors, close the terminal, and never open it again.

Don't do that.

Here's the sequence that works:

Step 1: Get the full picture 

npx fallow
Enter fullscreen mode Exit fullscreen mode

Do not panic at the output. You're not fixing everything today. You're learning the shape of the problem.

Step 2: Initialize your config 

npx fallow init
Enter fullscreen mode Exit fullscreen mode

This creates a .fallow/config.json where you declare your entry points, ignored patterns, and thresholds. Without this, Fallow doesn't know that src/index.ts is where your app starts — and it'll flag things that aren't actually dead.

Set your entry points honestly. Don't cheat by marking everything as an entry point to make the numbers look good.

Step 3: Triage by category 

npx fallow dead-code --unused-files   # Low-hanging fruit. Delete them.
npx fallow dead-code --unused-deps    # Package.json bloat. Remove them.
npx fallow dead-code --unused-exports # The sneaky ones. Investigate first.
npx fallow dupes                       # Find the clone groups.
npx fallow health                      # Find the complexity hotspots.
Enter fullscreen mode Exit fullscreen mode

Don't try to fix everything at once. Pick the highest-severity items — unused files and high-instance clones — and batch them into a cleanup PR.

Step 4: Preview before you delete 

npx fallow fix --dry-run
Enter fullscreen mode Exit fullscreen mode

Fallow can auto-remove dead exports and unused dependencies. Always run --dry-run first. Review what it plans to touch. Then apply it.

Step 5: Lock it into CI

Once the repo is clean, keep it clean.

npx fallow audit
Enter fullscreen mode Exit fullscreen mode

audit runs only on changed files — perfect for PR checks. Add it to your GitHub Actions pipeline with --fail-on-issues and you've made "don't introduce new dead code" a team policy, not a gentleman's agreement.

For CSS/SCSS People: Yes, Fallow Covers That Too

If you're using CSS Modules, Fallow treats every class in your .module.css file as an exported symbol.

If that class isn't referenced anywhere in your component code, it shows up as an unused export.

/* button.module.css */
.primaryBtn { ... }   /* ✅ Used */
.legacyBtn { ... }    /* ❌ Unused — Fallow flags this */
Enter fullscreen mode Exit fullscreen mode

It also resolves @use and @forward chains in SCSS, tracks Tailwind's @import, and handles partials. This is not an afterthought. The CSS analysis is first-class.

The Metrics Cheat Sheet

Keep this somewhere visible.

Metric Target Warning Action Needed
Duplication % < 5% 5–15% > 15%
Cyclomatic Complexity ≤ 20 21–50 > 50
Cognitive Complexity ≤ 15 16–30 > 30
CRAP Score < 30 30–99 ≥ 100
Complexity Density < 0.3 0.3–0.5 > 0.5

The health badge gives you an A–F grade for the whole project. A = 85+. F = you have a conversation to have with your team.

The Honest Part

Fallow will not fix your codebase.

You will.

What Fallow does is remove the excuse of not knowing. Before this, you could say "we don't know where the dead code is." That excuse is gone now. Before this, you could say "we can't measure duplication." Gone.

The tool is free to start. The refactoring takes discipline.

But the teams that do this — that actually clean the backlog, set thresholds, and gate new code in CI — those teams ship faster. Not because they have fewer lines of code, but because the lines they have are lines they understand.

That's the whole point.

What to Do Right Now

Not "this sprint." Right now.

npx fallow
Enter fullscreen mode Exit fullscreen mode

Look at the output. Pick the most embarrassing finding — the one you already suspected existed but never wanted to confirm. Fix that one thing.

Then run it again.

Have you run Fallow on your project yet? Drop your findings in the comments — the duplication % especially. No judgment. Only solidarity.

Tags: typescript javascript webdev tooling

Top comments (0)