nclean

A framework-aware Node.js project cleanup CLI tool that automatically detects your project type and cleans dependencies, build outputs, and caches safely.

Features

• Framework-aware detection - Automatically detects 15+ frameworks
• Three-tier detection - Config files → Dependencies → Directory structure
• Monorepo support - Recursive cleaning with depth control
• Safe by default - Dry-run mode, protected paths, confirmation prompts
• Cross-platform - Works on macOS, Linux, Windows
• No configuration needed - Works out of the box

Installation

npm install -g nclean

Quick Start

# Clean everything in current directory
nclean

# Clean specific directory
nclean ./my-project

# Preview what will be deleted (dry-run)
nclean --dry-run

# Clean recursively in monorepo
nclean --recursive

Commands

nclean [path] (default)

Clean all dependencies, build outputs, and caches.

nclean
nclean ./my-project

nclean deps [path]

Clean only dependencies (node_modules, etc.).

nclean deps
nclean deps ./frontend

nclean build [path]

Clean only build outputs (dist, build, .next, etc.).

nclean build
nclean build ./apps/api

nclean cache [path]

Clean only cache directories and files (.eslintcache, .turbo, etc.).

nclean cache
nclean cache ./apps/web

Options

| Option | Alias | Description | |--------|-------|-------------| | --dry-run | -d | Preview what will be deleted without actually deleting | | --force | -f | Skip confirmation prompts | | --verbose | -v | Show detailed output | | --quiet | -q | Suppress non-error output | | --recursive | -r | Process subdirectories (monorepo mode) | | --depth <number> | | Depth limit for recursive mode (default: 3) | | --exclude <patterns...> | | Exclude specific paths from cleaning |

Supported Frameworks

Web Frameworks

• Next.js - .next, out
• Nuxt - .nuxt, .output, dist
• Vite - dist, .vite
• Webpack - dist, build
• Create React App - build
• Gatsby - .cache, public
• Remix - .cache, build, public/build
• Astro - dist, .astro
• SvelteKit - .svelte-kit, build

Backend Frameworks

• NestJS - dist

Desktop & Mobile

• Electron - dist, out, release
• Tauri - src-tauri/target
• React Native - android/build, ios/build, .expo
• Expo - .expo, dist

Testing Tools

• Jest - .jest, coverage
• Vitest - .vitest, coverage
• Playwright - test-results, playwright-report
• Cypress - .cypress, cypress/screenshots, cypress/videos

Monorepo Tools

• Turborepo - .turbo
• Nx - .nx

Development Tools

• Storybook - storybook-static

Common Targets (all projects)

• node_modules
• .eslintcache, .prettiercache, tsconfig.tsbuildinfo
• *.log files

Safety Features

• Protected paths - System paths like /, /home, /Users, $HOME are never deleted
• Path traversal validation - Prevents escaping project root
• Dry-run mode - Preview changes before executing
• Idempotent operations - Safe to run multiple times
• Confirmation prompts - Requires approval before deletion (skip with --force)

Monorepo Support

Perfect for monorepos using pnpm workspaces, Yarn workspaces, Lerna, Turborepo, or Nx:

# Clean all workspaces
nclean --recursive

# Limit recursion depth
nclean --recursive --depth 2

# Exclude specific paths
nclean --recursive --exclude node_modules/.cache

Examples

# Clean a Next.js project
nclean ./next-app

# Clean only build artifacts in monorepo
nclean build --recursive

# Preview cleanup with verbose output
nclean --dry-run --verbose

# Skip confirmation for CI/CD
nclean --force

# Clean but keep specific directories
nclean --recursive --exclude apps/api/dist

Development

# Clone repository
git clone https://github.com/AkaraChen/nc.git
cd nc

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run dev
npm run test:watch

# Lint and format
npm run lint
npm run format

Test Coverage

• 302 tests passing
• 97.43% coverage
• Unit tests: 189 tests
• E2E tests: 68 tests

License

MIT