🚀 One Image Optimizer

A powerful npm package tool to automatically compress, rename, and convert your images to WebP format.

✨ Features

• 🗜️ Auto-compress images larger than 1MB
• 🏷️ Smart rename images based on their folder names
• 🔄 Convert to WebP for optimal web performance
• 🗑️ Empty folders utility to clean up directories
• ⚙️ Configurable settings via config file
• ✅ Safe - Asks for confirmation before making changes

📦 Installation

npm install one-image-optimizer

After installation, a configuration file one-image-optimizer.config.js will be automatically created in your project root.

🛠️ Setup

1. Edit the config file that was created in your project root:

// one-image-optimizer.config.js
module.exports = {
  ROOT_FOLDER: './assets/images',  // 👈 Change this to your images folder
  COMPRESS_THRESHOLD_MB: 1,
  MAX_WIDTH: 1920,
  MAX_HEIGHT: 1080,
  WEBP_QUALITY: 80,
  JPEG_QUALITY: 75,
  IMAGE_EXTENSIONS: ['.jpg', '.jpeg', '.png', '.webp', '.gif', '.bmp', '.tiff']
};

2. Set your ROOT_FOLDER to point to your images directory

🎯 Usage

Full Optimization (All Steps)

Run all optimization steps in sequence:

npx one-image-optimizer

Or if installed globally:

one-image-optimizer

This will:

1. ✅ Compress all images larger than 1MB
2. ✅ Rename images based on folder names
3. ✅ Convert all images to WebP format

Note: You'll be asked to confirm before the process starts.

Individual Commands

Run specific optimization steps:

# Compress images only
npx oio-compress

# Convert to WebP only
npx oio-webp

# Rename images only
npx oio-rename

# Empty all files in folders (⚠️ destructive!)
npx oio-empty

Tip: You can also install globally to use shorter commands:

npm install -g one-image-optimizer

# Then use without npx:
one-image-optimizer
oio-compress
oio-webp
oio-rename

📋 How It Works

1. Compression

• Scans your ROOT_FOLDER for images larger than COMPRESS_THRESHOLD_MB
• Compresses them while maintaining quality
• Resizes to max dimensions if needed

2. Renaming

• Renames images based on their parent folder name
• Format: {foldername}image1.jpg, {foldername}image2.jpg, etc.
• Removes spaces from folder names

3. WebP Conversion

• Converts all images to WebP format
• Deletes original files after successful conversion
• Removes duplicate non-WebP versions

4. Empty Folders

• Deletes all files within the target folder
• Keeps folder structure intact
• ⚠️ Use with caution!

⚙️ Configuration Options

| Option | Default | Description | |--------|---------|-------------| | ROOT_FOLDER | './assets/images' | Root directory containing your images | | COMPRESS_THRESHOLD_MB | 1 | Compress images larger than this (in MB) | | MAX_WIDTH | 1920 | Maximum width for compressed images | | MAX_HEIGHT | 1080 | Maximum height for compressed images | | WEBP_QUALITY | 80 | WebP compression quality (0-100) | | JPEG_QUALITY | 75 | JPEG compression quality (0-100) | | IMAGE_EXTENSIONS | ['.jpg', '.jpeg', ...] | Supported image formats |

🔒 Safety Features

• ✅ Confirmation prompt before running full optimization
• ✅ Extra confirmation for destructive operations (empty-folders)
• ✅ Clear warnings about what will be changed
• ✅ Validates config file and paths before running

📝 Example Workflow

# 1. Install the package
npm install one-image-optimizer

# 2. Edit one-image-optimizer.config.js
# Set ROOT_FOLDER to your images directory

# 3. Run full optimization
npx one-image-optimizer

# 4. Or run individual commands
npx oio-compress
npx oio-webp
npx oio-rename

🐛 Troubleshooting

Config file not found

• Make sure one-image-optimizer.config.js exists in your project root
• Run npm install again to recreate it

Path does not exist

• Check that ROOT_FOLDER in your config points to a valid directory
• Use relative paths from your project root (e.g., ./assets/images)

Permission errors on Windows

• The tool includes Windows file lock handling
• If issues persist, close any programs that might be using the images

📄 License

MIT

🤝 Contributing

Issues and pull requests are welcome!

Made with ❤️ for optimizing images