Start
Run Broom against a project for the first time and read the results.
Broom works on any JavaScript or TypeScript project without configuration. Change into the project and run a command:
cd my-projectbroom doctorbroom envbroom cleanEvery command accepts --cwd <path> to analyze another directory instead of the current one:
broom doctor --cwd ../other-projectbroom doctor gives the broadest picture: package metadata, lockfiles, installed modules, imports, .gitignore, git status and environment variables in one pass.
broom doctor Project fixture-next-app 1.0.0 Framework Next.js 15.1.0 Package manager unknown Node.js 24.22.1 TypeScript yes Git main ! Lockfiles No lockfile found; installs are not reproducible ! Installed node_modules not found; run "npm install" ✗ Imported packages 1 imported package(s) not declared in package.json axios — app/page.tsx ! Duplicate declarations 1 package(s) in both dependencies and devDependencies · npm scripts No "test" script ✗ .gitignore Environment file(s) not ignored by git: .env fix: Append node_modules/, .env and .env*.local to .gitignore (--fix) · Git on main, clean ! Environment variables 2 referenced but not defined (API_URL, SECRET_TOKEN) ✓ 4 checks passed (--verbose to list) 2 failed, 4 warnings, 4 passedEach line is a check. ✓ passed, ! is a warning, ✗ failed and · is informational. Run with --verbose to list passed checks and see more detail.
Broom only reports by default. Commands that can change files offer --fix, which always lists the changes and asks for confirmation first:
broom doctor --fix can create or extend .gitignore and add placeholders to .env.example.broom env --fix appends empty NAME= lines to .env.example.broom clean --fix lets you choose which files to delete.broom ports --kill lets you choose which processes to stop.Add --yes to skip prompts in scripts. When a confirmation is needed but no terminal is available, Broom exits with code 2 instead of guessing.
Audit commands exit with code 3 when they find issues, so they can fail a build. Use --json for machine-readable output.
broom env --quiet # exits 3 if env issues are foundbroom deps --json > deps-report.jsonSee Exit codes for exactly what counts as an issue for each command.
Found a problem in these docs? Open an issue on GitHub.