cleanup-project

A safe local Node.js cleanup utility for removing generated dependency and cache folders before a project is packed, zipped, copied, archived, or moved.

It is intentionally boring: no external dependencies, dry-run by default, explicit deletion only, and every delete target is checked against the resolved project root.

Why this exists

Folders like node_modules and .next/cache are generated artifacts. They can be huge, platform-specific, and easy to recreate from lockfiles or build commands. Archiving them wastes space, slows transfers, and can preserve stale cache state.

This tool recursively scans a project tree and reports cleanup targets such as nested node_modules folders, workspace caches, example app caches, and old generated folders inside copied projects.

This is also the first engraved Belt tool in this workspace: a small, trusted, low-ceremony utility that can live close at hand without becoming infrastructure. See docs/belt-taxonomy.md, docs/cleanup-project.belt.json, and the candidate catalog in docs/belt-tools.md.

By default it removes only conservative generated targets:

• node_modules
• .next/cache
• .turbo
• .parcel-cache
• .vite
• .cache
• coverage

It does not delete the full .next folder by default. Only .next/cache is targeted, because .next can contain build output someone may intentionally want to keep.

Quick start

This project runs directly with Node.js 18+ and has no runtime dependencies.

From this folder, install it globally:

npm run install:global

Then use it from any project:

cleanup-project
nmr
clean-project

All three commands run the same tool. nmr is the short alias.

You can also run it without global install:

node cleanup-project.js .
node cleanup-project.js "C:\Users\Administrator\Desktop\WORKINGDIR"

To remove the global command later:

npm run unlink:global

Dry run

Dry-run is the default. This scans and prints what would be deleted without removing anything. If no path is provided, the current directory is scanned.

Windows

cleanup-project
cleanup-project "C:\Users\Administrator\Desktop\WORKINGDIR"
nmr "C:\Users\Administrator\Desktop\WORKINGDIR"

WSL/Linux/macOS

cleanup-project
cleanup-project ./my-project
nmr ./my-project

Delete

Deletion requires --delete and asks for confirmation:

cleanup-project ./my-project --delete
nmr --delete
npm run clean

Skip the confirmation prompt for automation:

cleanup-project ./my-project --delete --yes
nmr --yes

--yes also enables delete mode:

cleanup-project ./my-project --yes

JSON output

Use --json for a machine-readable report:

cleanup-project ./my-project --json
cleanup-project ./my-project --delete --yes --json

Custom targets

Use --include to replace the default cleanup target list:

cleanup-project ./my-project --include ".next/cache,node_modules,.turbo"

Additional generated folders can be selected explicitly:

cleanup-project ./my-project --include "node_modules,tmp,temp,.npm,.yarn/cache,.pnpm-store,pnpm-store,dist/cache"

Use --exclude to skip directories by name or path pattern:

cleanup-project ./my-project --exclude "important-folder"
cleanup-project ./my-project --exclude "vendor/cache,fixtures/node_modules"

Limit recursion:

cleanup-project ./my-project --max-depth 20

Show detailed progress:

cleanup-project ./my-project --verbose

Print the installed version or default target list:

cleanup-project --version
cleanup-project --list-defaults

Safety guarantees

• Dry-run is enabled by default.
• Running cleanup-project with no path scans the current directory.
• Files are deleted only with --delete or --yes.
• --delete requires confirmation unless --yes is passed.
• All paths are resolved with path.resolve and fs.realpath.
• Every delete target is verified to stay inside the user-provided root.
• Symlinks are skipped by default.
• Symlinked directories are followed only with --follow-symlinks, and only when the real target is inside the selected root.
• Permission errors are logged and scanning continues.
• Deletion uses fs.rm(path, { recursive: true, force: true }).
• No shell rm, del, or platform-specific delete commands are used.

Example output

Project cleanup dry run
Root: C:\Users\Administrator\Desktop\WORKINGDIR
Mode: dry-run (no files deleted)

Summary
  Folders found: 4
  Estimated size: 184 MB
  node_modules folders: 2
  Cache folders: 2
  Skipped symlinks: 0
  Skipped permission errors: 0
  Other errors: 0

Targets
  - app/.next/cache (cache, 64 MB)
  - app/node_modules (node_modules, 98 MB)
  - packages/bar/.turbo (cache, 2 MB)
  - packages/foo/node_modules (node_modules, 20 MB)

No files were deleted. Pass --delete to remove targets after confirmation.

Test

Run the fixture test:

npm test

The test creates a temporary project with generated folders and source files, verifies dry-run discovery, runs delete mode with --yes, and confirms only the intended generated folders were removed.