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 --pluginsto 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
| Field | What it declares |
|---|---|
name | The name of the plugin. It is the only required field. |
enablers | The packages that turn the plugin on when package.json lists one of them. A name that ends with / matches a scope, for example @acme/. |
entryPoints | Globs of the files that the framework loads. Each match is an entry point. |
entryPointRole | runtime for code that ships. The default is support, for scripts and tooling that production mode leaves out. |
toolingDependencies | Packages that you use through a command, not through an import. Fallow does not report them as unused. |
usedExports | Export 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
| Problem | Cause | Fix |
|---|---|---|
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. |
Related
- Next: Plugins. Read it to see when fallow turns a plugin on, and what a plugin can change.
fallow plugin-schema: each field of a plugin file.fallow plugin-check: the output of the check.