Skip to content
Fallow home
All docs pages

Docs home

Write a plugin for your framework

Write a plugin file that tells fallow the conventions of a framework it does not know, check it with fallow plugin-check, and share it.

Your team runs its background jobs with an internal job runner, @acme/jobs. The runner loads each file in src/jobs/ and reads two exports of the file: schedule and handler. No file imports a job, so fallow reports each job as an unused file. Add the dependency @acme/jobs and the job src/jobs/nightly-cleanup.ts to the demo project, and the report shows it next to the real unused file:

● Unused files (2)
  src/jobs/nightly-cleanup.ts
  src/utils/legacy-currency.ts

A person who trusts this report deletes a job that runs each night. At the end of this guide, a plugin file tells fallow how your framework loads files, and fallow counts those files as used. A plugin tells fallow the conventions of one framework or tool. Fallow has built-in plugins for many frameworks. For an internal framework or a tool without a plugin, you write a plugin file in JSONC, JSON or TOML.

Before you start

  • Check that no built-in plugin fits. Run npx fallow list --plugins to see the active plugins.
  • Decide if you need a plugin. For one or two files, add them to entry. Write a plugin when the framework has a rule that applies to many files: a directory, a file name pattern, or export names that it reads.

The job of the example has the two exports that the runner reads, and one export that it does not read:

// src/jobs/nightly-cleanup.ts
import { formatPrice } from "../lib";

export const schedule = "0 3 * * *";

export const handler = async (): Promise<void> => {
  console.log(`Cleanup done: ${formatPrice(0)}`);
};

export const describe = (): string => "Remove old carts";

Steps

1. Write the plugin file

The plugin states the rule of the runner in a form that fallow reads. Put the file in the project root, because fallow loads each file in the project root whose name starts with fallow-plugin-.

// fallow-plugin-acme-jobs.jsonc
{
  "$schema": "./plugin-schema.json",
  "name": "acme-jobs",
  "enablers": ["@acme/jobs"],
  "entryPoints": ["src/jobs/*.ts"],
  "entryPointRole": "runtime",
  "toolingDependencies": ["@acme/jobs"],
  "usedExports": [
    { "pattern": "src/jobs/*.ts", "exports": ["schedule", "handler"] }
  ]
}

To get autocomplete in your editor, write the schema file next to the plugin:

npx fallow plugin-schema > plugin-schema.json

2. Understand each part

FieldWhat it declares
nameThe name of the plugin. It is the only required field.
enablersThe packages that turn the plugin on when package.json lists one of them. A name that ends with / matches a scope, for example @acme/.
entryPointsGlobs of the files that the framework loads. Each match is an entry point.
entryPointRoleruntime for code that ships. The default is support, for scripts and tooling that production mode leaves out.
toolingDependenciesPackages that you use through a command, not through an import. Fallow does not report them as unused.
usedExportsExport names that the framework reads from matching files. Fallow counts them as used.

Other fields cover config files (configPatterns), files that are always used (alwaysUsed) and class members that the framework calls (usedClassMembers). manifestEntries reads entry points from manifest files. A detection object replaces enablers when the plugin depends on more than one condition, for example a package and a config file. fallow plugin-schema prints each field with its description. A plugin without enablers and without detection never turns on.

3. Check that the plugin is active

A plugin that does not turn on changes nothing, and the report gives no sign of it. Check it first:

npx fallow plugin-check
plugin 'acme-jobs': active, 0 manifestEntries rules

0 warnings.

fallow plugin-check changes nothing and exits with code 0. When the plugin is not active, it gives the reason. With a wrong package name in enablers, the output is:

plugin 'acme-jobs': INACTIVE (no enabler present; requires one of these dependencies: @acme/job-runner)

4. Check the entry points and the findings

An active plugin is not yet a correct plugin: its globs must also match your files. The list of entry points shows the result:

npx fallow list --entry-points
Found 4 entry points
scripts/seed.js (package.json script `seed`)
src/index.ts (package.json main)
src/jobs/nightly-cleanup.ts (acme-jobs)
src/math.test.ts (vitest)

The job is an entry point now, and the source names the plugin. Run the analysis again:

npx fallow dead-code --unused-files --unused-exports
● Unused files (1)
  src/utils/legacy-currency.ts
  Files not reachable from any entry point
  https://fallow.tools/docs/explanations/dead-code/#unused-files

● Unused exports (4)
  src/jobs/nightly-cleanup.ts
    :9 describe
  src/lib/format.ts
    :3 formatPercent
  src/lib/index.ts
    :1 formatPercent (re-export)
  src/services/orders.ts
    :18 cancelOrder

The job file is no longer unused. Fallow checks the other exports of the job, because the plugin names the exports that the framework reads. The runner does not read describe, so fallow reports it. The other three findings were in the report before the plugin.

5. Share the plugin

The plugin works on your machine. Commit the plugin file, and each run in the repository loads it, also in CI. Fallow also loads plugins from .fallow/plugins/, but fallow tells Git to ignore the .fallow/ directory, so a plugin there stays on your machine.

To keep plugin files in another directory, list the directory or the files in plugins:

// .fallowrc.jsonc
{
  "plugins": ["tools/fallow-plugins/"]
}

Entry points from manifest files

A glob works when the framework finds its files by name. Some frameworks declare the entry file of each package in a manifest file instead, for example a kibana.jsonc in each plugin directory. A static glob cannot read the fields of these files. A manifestEntries rule finds the manifests, reads them, and makes the paths that they name entry points:

// fallow-plugin-acme.jsonc
{
  "name": "acme",
  "detection": { "type": "fileExists", "pattern": "**/acme.jsonc" },
  "entryPointRole": "runtime",
  "manifestEntries": [
    {
      "manifests": "**/acme.jsonc",
      "when": { "type": "plugin" },
      "entries": [
        { "path": "public/index.{ts,tsx}", "when": { "plugin.browser": true } },
        { "path": "${plugin.extraPublicDirs}/index.{ts,tsx}" }
      ]
    }
  ]
}

Each path is relative to the directory of the manifest. ${plugin.extraPublicDirs} gives one entry for each value of that manifest field. A when condition compares fields with strict equality. For each rule, fallow plugin-check --format json shows the manifests that matched and the entries that the rule added. It also warns about each glob or field that matched nothing. Fallow has a built-in plugin for Kibana.

Check the result

npx fallow plugin-check
npx fallow list --entry-points

The plugin is active, and the files of the framework show the plugin name as their source.

If it fails

ProblemCauseFix
The plugin is INACTIVE.No package in package.json matches enablers.Correct the package name, or use detection.
The plugin is not in the output of plugin-check.Fallow did not find the file.Start the file name with fallow-plugin- in the root, or list it in plugins.
The files are still unused.The glob does not match the paths.Compare the glob with the paths of fallow list --files. Each path is relative to the project root.
A file of the framework is used, but its exports are reported.usedExports does not name them.Add the export names that the framework reads.