Why prune-mod?

Node.js projects often have large node_modules folders filled with unnecessary files like documentation, tests, and build configs. These files take up valuable disk space and slow down deployments. prune-mod safely removes these files while keeping your application working perfectly.

Key Benefits:

• Reduce size by 60% - Dramatically shrink your node_modules
• Faster deployments - Less data to transfer and extract
• Lower storage costs - Save money on serverless and container deployments
• Safe by default - Never breaks your application
• Lightning fast - Process thousands of files in seconds
• Smart runtime detection - Automatically uses the fastest available runtime (Bun or Node.js)
• Workspace/Monorepo support - Automatically detects and prunes all packages in your monorepo

Quick Start

# Install globally
npm install -g @usex/prune-mod

# Use in any project
prune-mod

# Or run without installing
npx @usex/prune-mod

Installation

npm / yarn / pnpm

# npm
npm install -g @usex/prune-mod

# yarn
yarn global add @usex/prune-mod

# pnpm
pnpm add -g @usex/prune-mod

Bun (Recommended)

bun install -g @usex/prune-mod

Run without installing

# npm
npx @usex/prune-mod

# bun
bunx @usex/prune-mod

Usage

Basic usage

# Clean current project's node_modules
prune-mod

# Clean specific directory
prune-mod ./my-project/node_modules

# Preview what will be removed (safe to run)
prune-mod --dry-run

# See detailed output
prune-mod --verbose

Command options

Usage:
  prune-mod [options] [directory]

Options:
  -v, --verbose         Show detailed output
  --exclude <pattern>   Don't remove files matching this pattern
  --include <pattern>   Always remove files matching this pattern
  -d, --dry-run         Preview changes without removing files
  -w, --workspace       Enable workspace/monorepo mode
  --workspace-root <dir> Specify workspace root (auto-detected if not provided)
  --no-root             Skip pruning root node_modules in workspace mode
  --experimental-default-files Enable experimental extended file list for more aggressive pruning
  -h, --help            Show help

Examples:
  prune-mod                              # Clean ./node_modules
  prune-mod ./dist/node_modules         # Clean specific directory
  prune-mod --exclude "*.config.js"    # Keep config files
  prune-mod --dry-run --verbose         # Preview with details
  
Workspace Examples:
  prune-mod --workspace                 # Auto-detect and prune all packages
  prune-mod -w --no-root               # Prune only package node_modules
  prune-mod -w --workspace-root /monorepo # Specify workspace root
  
Experimental Examples:
  prune-mod --experimental-default-files    # Use extended file list
  prune-mod -w --experimental-default-files # Combine with workspace mode

Real-world examples

Before deployment:

# Install production dependencies
npm ci --production

# Remove unnecessary files
prune-mod --verbose

# Your bundle is now 60% smaller!

Docker builds:

FROM node:18-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci --production

# Clean up node_modules
RUN npx @usex/prune-mod

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .

CMD ["node", "index.js"]

Custom patterns:

# Keep specific files you need
prune-mod --exclude "*.d.ts" --exclude "LICENSE"

# Remove additional file types
prune-mod --include "*.log" --include "*.tmp"

What gets removed?

prune-mod safely removes these types of files:

Documentation files

• README files (README.md, README.txt, etc.)
• CHANGELOG and HISTORY files
• LICENSE and COPYRIGHT files
• Documentation directories (docs/, doc/)

Development files

• Test files and directories (test/, tests/, tests/)
• Example files and directories
• Source maps (*.map files)
• TypeScript config (tsconfig.json, tslint.json)

Build and config files

• Linting configs (.eslintrc, .prettierrc, etc.)
• CI/CD configs (.github/, .circleci/, etc.)
• Editor configs (.vscode/, .idea/, .editorconfig)
• Build tool configs (webpack.config.js, etc.)

Temporary files

• Coverage reports
• Log files
• Temporary directories
• Cache files

Important: prune-mod never removes:

• Main entry files (package.json main/module/exports)
• Runtime dependencies
• Binary executables
• Critical system files

Experimental Extended File List

For even more aggressive space savings, prune-mod offers an experimental mode that removes additional safe files:

# Enable experimental extended file list
prune-mod --experimental-default-files

# Use with other options
prune-mod --experimental-default-files --workspace --verbose

Experimental mode adds 140+ additional file patterns including:

• Extended documentation files (CHANGELOG.md, CODE_OF_CONDUCT.md, SECURITY.md)
• Advanced configuration files (webpack.config., rollup.config., vite.config.*)
• Git and version control files (.gitignore, .gitkeep, .dockerignore)
• CI/CD configurations (azure-pipelines.yml, .drone.yml, buildkite.yml)
• Code quality tools (.codeclimate.yml, codecov.yml, sonar-project.properties)
• Build outputs and caches (dist/, build/, .cache/, .next/, .nuxt/)
• Source maps and minified files (*.map, *.min.js, *.min.css)
• Environment and runtime files (.env.example, .nvmrc, .python-version)

Safety note: Experimental mode is thoroughly tested but more aggressive. Always test with --dry-run first to ensure it meets your needs.

Programming API

Use prune-mod in your Node.js applications:

import { Pruner } from '@usex/prune-mod';

const pruner = new Pruner({
  dir: './node_modules',
  verbose: true,
  dryRun: false,
  exceptions: ['*.config.*'], // Files to keep
  globs: ['**/*.tmp'],        // Files to remove
  experimental: {
    defaultFiles: true        // Enable extended file list
  }
});

const stats = await pruner.prune();

console.log(`Removed ${stats.filesRemoved} files`);
console.log(`Saved ${stats.sizeRemoved} bytes`);
console.log(`Processed ${stats.filesTotal} total files`);

Workspace API

import { Pruner, WorkspaceDetector } from '@usex/prune-mod';

// Auto-detect and prune workspace
const pruner = new Pruner({
  dir: '.',
  workspace: true,
  includeRoot: true,
  verbose: true
});

const stats = await pruner.prune();

// Or manually detect workspace info
const detector = new WorkspaceDetector();
const info = await detector.detect('.');
console.log(`Workspace type: ${info.type}`);
console.log(`Packages found: ${info.packages.length}`);

Configuration options

interface PrunerOptions {
  dir?: string;           // Target directory (default: "node_modules")
  verbose?: boolean;      // Show detailed output (default: false)
  dryRun?: boolean;       // Preview mode (default: false)
  exceptions?: string[];  // Patterns for files to keep
  globs?: string[];       // Additional patterns to remove
  files?: string[];       // Custom file names to remove
  directories?: string[]; // Custom directory names to remove
  extensions?: string[];  // Custom file extensions to remove
  
  // Workspace options
  workspace?: boolean;    // Enable workspace mode (default: false)
  workspaceRoot?: string; // Custom workspace root (auto-detected if not set)
  includeRoot?: boolean;  // Include root node_modules (default: true)
  
  // Experimental options
  experimental?: {
    defaultFiles?: boolean; // Enable extended file list (default: false)
  };
}

Performance

Benchmark results on a typical Next.js project:

Results vary by project, but most see 40-70% size reduction.

Smart Runtime Detection

prune-mod features intelligent runtime detection that automatically selects the optimal JavaScript runtime for maximum performance:

How it works

When you run prune-mod, the tool automatically detects your environment and chooses the best runtime:

# prune-mod automatically detects and uses:
# → Bun (if available) - Up to 3x faster processing
# → Node.js (fallback) - Reliable and widely available

Performance comparison

Zero configuration required

The runtime detection is completely automatic:

• Development with Bun installed: Uses Bun for lightning-fast processing
• CI/CD pipelines: Automatically adapts to available runtime
• Docker containers: Works with any Node.js or Bun base image
• Legacy systems: Falls back gracefully to Node.js

Benefits for different environments

Local Development:

• Bun users get 3x faster pruning
• Instant feedback with --dry-run
• Reduced waiting time in development workflow

CI/CD Pipelines:

• Automatically uses fastest available runtime
• Reduces build times significantly
• Works in any containerized environment

Production Deployments:

• Guaranteed compatibility with Node.js
• Optimal performance when Bun is available
• No runtime-specific configuration needed

Workspace/Monorepo Support

prune-mod intelligently detects and handles all major monorepo tools, making it perfect for large-scale projects with multiple packages.

Supported Workspace Types

How Workspace Mode Works

When you run prune-mod --workspace, it:

1. Auto-detects your monorepo type and structure
2. Identifies all workspace packages automatically
3. Prunes both root and package-level node_modules
4. Preserves workspace integrity and symlinks
5. Reports consolidated statistics for all packages

Workspace Examples

Basic workspace pruning:

# Auto-detect and prune entire monorepo
prune-mod --workspace

# Preview what will be removed
prune-mod -w --dry-run --verbose

Advanced workspace control:

# Skip root node_modules (only prune packages)
prune-mod -w --no-root

# Specify custom workspace root
prune-mod -w --workspace-root /path/to/monorepo

# Combine with other options
prune-mod -w --exclude "*.config.js" --verbose

Real-world monorepo example:

# In a large Nx monorepo
cd my-nx-workspace
prune-mod --workspace

# Output:
# Detected nx workspace at /my-nx-workspace
# Found 25 workspace packages
# Pruning root node_modules at /my-nx-workspace/node_modules
# Pruning package node_modules at /my-nx-workspace/apps/web/node_modules
# ...
# files removed: 15,234
# size removed: 285 MB

Workspace Performance

Benchmark on a typical monorepo with 20 packages:

Best Practices for Workspaces

1. CI/CD Integration:

   # GitHub Actions example
   - name: Install and prune
     run: |
       npm ci
       npx @usex/prune-mod --workspace

2. Docker Optimization:

   FROM node:18 AS builder
   WORKDIR /app
   COPY . .
   RUN npm ci && npx @usex/prune-mod -w
   
   FROM node:18-alpine
   COPY --from=builder /app .

3. Selective Pruning:

   # Only prune specific packages (manual mode)
   prune-mod ./packages/app-a/node_modules
   prune-mod ./packages/app-b/node_modules

Use Cases

Serverless functions

Reduce cold start times and stay under size limits:

npm ci --production
prune-mod
zip -r function.zip .

Docker containers

Smaller images mean faster pulls and deployments:

RUN npm ci --production && npx @usex/prune-mod

CI/CD pipelines

Speed up builds and deployments:

- name: Install dependencies
  run: npm ci --production
  
- name: Clean node_modules
  run: npx @usex/prune-mod --verbose

Local development

Free up disk space on your machine:

# Clean all projects in a directory
find . -name "node_modules" -type d -exec prune-mod {} \;

Safety

prune-mod is designed to be safe:

• Respects package.json - Never removes main entry files
• Dry run mode - Preview changes before applying them
• Extensive testing - Tested on thousands of real packages
• Rollback friendly - Just run npm install to restore files
• Non-destructive - Only removes files that can be regenerated

Requirements

• Node.js 18+ or Bun 1.0+
• Works on Windows, macOS, and Linux

Contributing

We welcome contributions! Here's how to help:

1. Report bugs - Open an issue with details
2. Suggest features - Tell us what you need
3. Submit code - Fork, branch, code, test, PR
4. Improve docs - Help others understand the tool
5. Share feedback - Let us know how it works for you

Development setup

# Clone the repository
git clone https://github.com/ali-master/prune-mod.git
cd prune-mod

# Install dependencies
bun install

# Run tests
bun test

# Start development
bun run dev

# Build for production
bun run build

FAQ

Q: Is it safe to use in production?
A: Yes! prune-mod only removes files that aren't needed at runtime.

Q: What if I need a file that gets removed?
A: Use --exclude to keep specific files, or just run npm install to restore everything.

Q: How much space will I save?
A: Typically 40-70% depending on your dependencies. Use --dry-run to preview.

Q: Does it work with Yarn/pnpm?
A: Yes! prune-mod works with any package manager.

Q: Can I use it in automated scripts?
A: Absolutely! It's designed for CI/CD pipelines and automated deployments.

License

MIT License - see LICENSE file for details.

Related Tools

• node-prune - Go-based alternative
• npm-prune - Built-in npm command for dev dependencies
• clean-modules - Similar cleaning tool