Skip to content
Fallow home
All docs pages

Docs home

Set up fallow in a monorepo

Check that fallow finds each package of a monorepo, scope a run to one package or to the changed packages, and give a package its own rules.

Your repository holds several packages, and one report for all of them is too long for one team to act on. At the end of this guide, fallow analyzes each package of your monorepo, each team reads the findings of its own package, and CI checks only the packages that a change touches.

The order of the steps matters. Fallow analyzes the whole repository in one run, and an import from one workspace to another is an ordinary import. So a package that fallow does not find makes wrong findings in each later step. First check the packages, then scope the report.

Before you start

  • Run each command from the root of the repository, where the workspace config of your package manager is: pnpm-workspace.yaml, or workspaces in package.json.
  • Install the dependencies. Your package manager then links the workspace packages in node_modules.

The examples use the monorepo of Workspaces: packages/ui (@acme/ui), packages/web (@acme/web, which imports Button from @acme/ui and lists the unused left-pad), and tools/codegen, which no workspace pattern declares.

Steps

1. Check that fallow finds each package

npx fallow list --workspaces
Discovered 2 workspaces
  @acme/ui -> packages/ui (internal dep)
  @acme/web -> packages/web
1 workspace discovery diagnostic:
  - Directory 'tools/codegen' contains package.json but is not declared as a workspace. Add it to package.json workspaces or pnpm-workspace.yaml, or add it to ignorePatterns.

Each line gives the package name and its directory. internal dep marks a package that another workspace lists as a dependency. The diagnostic names a package that fallow did not find: until you fix it, fallow reports tools/codegen/index.js as an unused file. npx fallow workspaces prints the same list. Workspace diagnostics lists each problem that it can report.

To add the package, add its directory to the workspace config of your package manager, or to workspaces.patterns in the fallow config file:

// .fallowrc.jsonc
{
  "workspaces": { "patterns": ["tools/*"] }
}

Run npx fallow list --workspaces again. It now shows @acme/codegen -> tools/codegen and no diagnostic.

2. Run fallow on the whole repository

With each package known, run the analysis once for the whole repository:

npx fallow dead-code
  3 entry points detected (3 package.json)

── Unused Code ─────────────────────────────────────

● Unused files (1)
  packages/ui/src/old-card.ts
  Files not reachable from any entry point
  https://fallow.tools/docs/explanations/dead-code/#unused-files

── Dependencies ─────────────────────────────────────

● Unused dependencies (1)
  left-pad (packages/web/package.json)
  Listed in dependencies but never imported
  https://fallow.tools/docs/explanations/dead-code/#unused-dependencies

✗ 1 file · 1 unused dependency (0.14s)

The main or exports field of each package gives one entry point, so the run finds 3. Button and Badge are not in the list, because packages/web imports them through @acme/ui. A dependency finding names the package.json that lists the package.

3. Scope a run to one package

The team of @acme/web needs only its own findings:

npx fallow dead-code --workspace @acme/web
── Dependencies ─────────────────────────────────────

● Unused dependencies (1)
  left-pad (packages/web/package.json)
  Listed in dependencies but never imported
  https://fallow.tools/docs/explanations/dead-code/#unused-dependencies

Fallow still analyzes the whole repository, so a use in another package counts. It reports only the findings of @acme/web. --workspace also takes a glob, a list and a ! exclusion, for example --workspace 'packages/*,!@acme/web'.

4. Scope a run to the changed packages

In CI, you do not know the package in advance: it depends on the pull request. --changed-workspaces takes a git ref and reports the packages that changed since that ref. Here a branch changed only packages/ui/src/badge.ts:

npx fallow dead-code --changed-workspaces main
── Unused Code ─────────────────────────────────────

● Unused files (1)
  packages/ui/src/old-card.ts
  Files not reachable from any entry point
  https://fallow.tools/docs/explanations/dead-code/#unused-files

✗ 1 file (0.07s)

The left-pad finding of @acme/web is not in the report, because the branch did not touch that package. You cannot combine --changed-workspaces with --workspace. For a check of the changed files only, use the changed-code check.

5. Give one package its own rules

A scoped report can still fail the run on a finding that the team of that package accepts for now. Fallow reads one config file, at the root, and a config file inside a package has no effect on a run from the root. To change a rule for one package, add an overrides entry to the root config file:

// .fallowrc.jsonc
{
  "overrides": [
    {
      "files": ["packages/ui/**"],
      "rules": { "unused-files": "warn" }
    }
  ]
}
npx fallow dead-code --workspace @acme/ui
● Unused files (1)
  packages/ui/src/old-card.ts
  Files not reachable from any entry point
  https://fallow.tools/docs/explanations/dead-code/#unused-files

⚠ 1 file (0.04s)

The finding is a warning now, and the exit code is 0. Some rules are about the whole project, for example unused-dependencies, and overrides does not change them. For the dependencies of one package, use ignoreDependencies under workspaces.settings. The key is the directory of the package, as fallow list --workspaces prints it, for example packages/web.

6. Mark the packages that you publish

By default, fallow does not check the exports of an entry point, so an unused export in the entry of a package stays hidden. To find these exports too, turn on includeEntryExports:

// .fallowrc.jsonc
{
  "includeEntryExports": true
}
npx fallow dead-code --unused-exports
● Unused exports (1)
  packages/ui/src/index.ts
    :2 Badge (re-export)
  Exported symbols with no known consumers
  https://fallow.tools/docs/explanations/dead-code/#unused-exports

No package in the repository imports Badge. When code outside the repository uses @acme/ui, Badge is part of its public API. Mark the package as public: add "publicPackages": ["@acme/ui"] to the same config file. Fallow then checks the entry exports of @acme/web and @acme/codegen, and keeps the public API of @acme/ui. The Badge finding goes away.

Check the result

npx fallow list --workspaces
npx fallow dead-code --changed-workspaces main

The first command lists each package and no diagnostic. The second command reports only the packages that your branch changed.

If it fails

Most problems in a monorepo come from a package that fallow does not see, or from a config in the wrong place:

ProblemCauseFix
A package is not in list --workspaces.The workspace config of the package manager does not declare it.Add the directory to workspaces.patterns.
An import of a workspace package is unresolved.The package is not linked in node_modules, or its exports point to a build output that does not exist.Install the dependencies. Check the exports field of the package.
A rule in packages/x/.fallowrc.json has no effect.Fallow reads the config file of the root.Move the rule to an overrides entry in the root config file.
--changed-workspaces failed for ref and exit code 2.Git cannot find the ref, for example in a shallow clone.Fetch the history in CI, for example with fetch-depth: 0 on actions/checkout.