Start
Broom documentation
What Broom is, what it does, and where to start.
Broom is a fast, lightweight, cross-platform CLI for auditing, maintaining and inspecting JavaScript and TypeScript projects. It is a single broom command with seven subcommands, each answering one question about your project.
commands
broom env environment variables vs. .env filesbroom clean potentially unused files and assetsbroom ports processes on common dev portsbroom recap Markdown summaries of local git historybroom doctor project health checksbroom deps declared vs. used dependenciesbroom stats size and language overviewBroom analyzes source with a real parser (Babel), never sends anything over the network, never deletes or kills anything without asking, and never prints the values in your .env files.
Start here
- Installation: requirements and install commands.
- Getting started: your first run, and how to read the results.
- Global options: flags every command accepts, including
--json. - Configuration: the optional
broom.config.json. - Exit codes: what
0,1,2and3mean, for CI.
Supported platforms
macOS, Linux and Windows. Paths are normalized internally, so Windows separators do not affect results. broom ports uses platform-specific process discovery.
Limitations
These are deliberate, documented boundaries of version 0.1.0:
- Static analysis only.
cleananddepscannot see code paths built at runtime, which is why findings carry confidence levels or are labeled potential. cleanreports direct orphans. A file used only by another unused file is considered used; runcleanagain after removing files.- Template languages are not parsed.
.vue,.svelte,.astro,.htmland.md(x)are scanned for quoted paths andurl(); env references inside them are not detected. - Aliases come from tsconfig/jsconfig
paths/baseUrlplus the@/and~/conventions. Bundler-only aliases and package-basedextendsare not resolved. - Env files across a monorepo are evaluated as one pool.
Deno.envandBun.envare not detected. - Lockfiles are read with lightweight format-specific readers; Bun lockfiles are not parsed.
- Ports covers TCP listeners only. The Windows adapter is covered by parser unit tests but has not yet been exercised on a real Windows machine in this release.
- Source files over 1 MB are not parsed (they are usually generated) and are listed as skipped.
Found a problem in these docs? Open an issue on GitHub.