Skip to content
Fallow home
All docs pages

Docs home

Plugins

Learn how fallow knows the files and exports that a framework or tool uses by convention, and how it turns on a plugin.

Vitest loads src/math.test.ts because the file name ends in .test.ts, and no file of the demo project imports it. A framework or a tool often loads files that no import names. Fallow follows imports, so it needs one more source of facts for these files, and plugins give these facts.

The problem

Without knowledge of the test runner, fallow cannot reach the test file from an entry point. To see the result, remove vitest from devDependencies and run the same project again:

npx fallow dead-code --unused-files
  2 entry points detected (2 package.json)

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

● Unused files (3)
  src/math.test.ts
  src/utils/legacy-currency.ts
  src/utils/test-helpers.ts
  Files not reachable from any entry point

Fallow reports the test file and the helper that only the test imports as unused files. Both findings are wrong. If you delete the two files, the project loses its test.

Plugins

A plugin is the part of fallow that knows one framework or tool. Fallow turns it on when the project depends on that package. Fallow has more than 150 built-in plugins for frameworks, test runners, bundlers and other tools. Built-in plugins lists them.

Add vitest to devDependencies again, and the Vitest plugin is on. It makes src/math.test.ts an entry point, and both wrong findings go away.

How fallow turns on a plugin

The Vitest plugin turned on because of one line in package.json. That is the usual trigger: fallow reads the package.json of the project, and it turns on a plugin when one of its packages is in dependencies, devDependencies, peerDependencies or optionalDependencies. A plugin can name an exact package, for example vitest, or a scope, for example each package that starts with @storybook/.

Some plugins have other triggers:

  • A file in the project. For example, a tsconfig.json turns on the TypeScript plugin, also without a typescript dependency.
  • A package.json script that runs the tool.
  • A field in package.json that the tool reads.

In a monorepo, fallow turns on the plugins for each workspace from the package.json of that workspace. A plugin that one package turns on does not add entry points in another package.

To see the plugins that are on, run:

npx fallow list --plugins
Active plugins:
  - vitest
  - typescript

To see the entry points that the plugins and package.json add, run npx fallow list --entry-points. Each line names a file and its source, for example src/math.test.ts (vitest). Use the two lists when fallow reports a file or an export that your project uses: Trace a finding shows the steps.

What a plugin adds

Now you know when a plugin is on. What it changes in the report depends on the conventions of its tool. In a Next.js app, the plugin makes each page, layout and route handler an entry point, and it counts default, metadata and generateMetadata in a page as used. Without the plugin, fallow reports each page as an unused file.

Across all plugins, these are the kinds of facts that a plugin adds:

A plugin addsExample
Entry pointsThe Vitest plugin adds each test file. The Next.js plugin adds pages, layouts and route handlers.
Used exportsIn a Next.js page, the plugin counts default, metadata and generateMetadata as used.
Config filesThe plugin reads the config file of the tool, for example vite.config.ts, and finds more entry points and dependencies in it.
Files that are always usedFiles that the tool loads by their path.
Tooling dependenciesPackages that a tool runs from the command line or from its config. Fallow does not report them as unused.
Generated importsVirtual modules and path aliases that the framework makes when it builds. Fallow does not report them as unlisted or unresolved.
Class membersMethods that the framework calls, for example a lifecycle method. Fallow does not report them as unused.

A plugin reads a config file as source text. It does not run the config file.

What a plugin cannot do

A plugin knows only the conventions that it was written for. Some cases stay outside it:

  • A framework that has no plugin. Fallow then reports the files that the framework loads as unused files.
  • A config value that the config file computes when it runs, for example a path from an environment variable.
  • A convention of your own project, for example a folder of jobs that a scheduler loads by name.

For a framework or a convention of your own, write a plugin file. Write a plugin for your framework shows how. For a few files, the entry key of the config file is enough.

Next