@codext/project-image-compression
v1.0.2
Published
A CLI tool for compressing and optimizing images in bulk in a npm project
Downloads
310
Maintainers
Readme
project-image-compression
A powerful and flexible CLI tool for bulk image compression and optimization. This tool helps you automatically compress and resize images in a directory while maintaining quality and optionally converting them to WebP format.
Features
- 🖼️ Bulk image compression with customizable quality settings
- ↔️ Automatic image resizing while maintaining aspect ratio
- 🔄 Optional WebP conversion
- 📁 Custom output directory support
- 💾 Automatic backup creation
- 📊 Detailed compression statistics
- 🎯 Configurable via JSON file
- 🚀 Support for JPG, JPEG, PNG, and WebP formats
Installation
npm install @codext/project-image-compression
Quick Start
- Add the script to your package.json:
{
"scripts": {
"compress-images": "npx @codext/project-image-compression"
}
}
- Create an
img.config.json
file in your project root:
{
"quality": 80,
"maxWidth": 1920,
"maxHeight": 1080,
"convertToWebp": false,
"folder": "./images",
"skipExisting": true,
"createBackup": true,
"outputFolder": null
}
- Run the compression:
npm run compress-images
Configuration
Create an img.config.json
file in your project root with the following options:
| Option | Type | Default | Description | |--------|------|---------|-------------| | quality | Number | 80 | Output image quality (0-100) | | maxWidth | Number | 1920 | Maximum width of output images | | maxHeight | Number | 1080 | Maximum height of output images | | convertToWebp | Boolean | false | Convert images to WebP format | | folder | String | "./images" | Source folder containing images to process | | skipExisting | Boolean | true | Skip already processed images | | createBackup | Boolean | true | Create backup of original images | | outputFolder | String|null | null | Custom output directory (null to overwrite originals) |
Example Usage
Basic Compression
For basic image compression with default settings:
{
"folder": "./images",
"quality": 80
}
Convert to WebP
To compress and convert all images to WebP format:
{
"folder": "./images",
"quality": 85,
"convertToWebp": true,
"outputFolder": "./compressed"
}
High-Quality Resize
For resizing large images while maintaining high quality:
{
"folder": "./images",
"quality": 90,
"maxWidth": 1920,
"maxHeight": 1080,
"createBackup": true
}
CLI Output
The tool provides detailed statistics after processing:
- Number of images processed
- Total size reduced (in MB)
- Average compression percentage
- Processing status for each image
Example output:
✔ Image compression completed!
Stats:
- Images processed: 24
- Total size reduced: 15.7 MB
- Average compression: 65.3%
Error Handling
- The tool creates backups by default (can be disabled)
- Failed image processing is reported but doesn't stop the batch
- Invalid configuration files trigger helpful error messages
- Missing source directory prompts for creation
Requirements
- Node.js 12.0 or higher
- NPM or Yarn package manager
Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature
) - Commit your changes (
git commit -m 'Add some AmazingFeature'
) - Push to the branch (
git push origin feature/AmazingFeature
) - Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Credits
Built with: