{"id":34599149,"url":"https://github.com/flyingrobots/image-lite","last_synced_at":"2026-05-24T13:34:06.441Z","repository":{"id":301768395,"uuid":"1010231826","full_name":"flyingrobots/image-lite","owner":"flyingrobots","description":"Cut the fat. Keep the pixels.","archived":false,"fork":false,"pushed_at":"2025-06-28T18:55:58.000Z","size":134,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-25T23:43:22.503Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flyingrobots.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-28T16:23:30.000Z","updated_at":"2025-08-23T15:35:20.000Z","dependencies_parsed_at":"2025-06-28T18:36:27.960Z","dependency_job_id":"fdfc1a77-babd-4050-8c4d-aa57b84ce8e5","html_url":"https://github.com/flyingrobots/image-lite","commit_stats":null,"previous_names":["flyingrobots/image-lite"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/flyingrobots/image-lite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fimage-lite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fimage-lite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fimage-lite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fimage-lite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flyingrobots","download_url":"https://codeload.github.com/flyingrobots/image-lite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fimage-lite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33436554,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-24T13:13:05.286Z","status":"ssl_error","status_checked_at":"2026-05-24T13:13:03.728Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T12:07:32.489Z","updated_at":"2026-05-24T13:34:06.416Z","avatar_url":"https://github.com/flyingrobots.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./image-lite.webp\" alt=\"image-lite logo\" width=\"300\"\u003e\n\u003c/div\u003e\n\n# image-lite\n\nA high-performance batch image optimization tool built with Node.js and Sharp. Optimize thousands of images efficiently with support for modern formats (WebP, AVIF), automatic format conversion, and intelligent quality rules.\n\n## Features\n\n- 🚀 **High Performance** - Built on Sharp, the fastest Node.js image processing library\n- 🎯 **Smart Optimization** - Automatic format selection and quality optimization\n- 📦 **Batch Processing** - Process entire directories with subdirectory support\n- 🔄 **Multiple Formats** - Generate WebP, AVIF, and optimized originals\n- 🖼️ **Thumbnails** - Automatic thumbnail generation with configurable sizes\n- 📏 **Quality Rules** - Per-image quality settings based on patterns\n- 🔧 **Flexible Config** - JSON/YAML configuration with sensible defaults\n- 📊 **Progress Tracking** - Real-time progress bars and detailed statistics\n- 🛡️ **Error Recovery** - Resume interrupted jobs and retry failed images\n- 🔌 **Git LFS Support** - Automatic Git LFS detection and pulling\n\n## Installation\n\n```bash\nnpm install -g image-lite\n```\n\nOr use directly with npx:\n\n```bash\nnpx image-lite\n```\n\n## Quick Start\n\n1. Create a directory structure:\n   ```\n   your-project/\n   ├── original/       # Put your source images here\n   └── optimized/      # Optimized images will be generated here\n   ```\n\n2. Add images to the `original/` directory\n\n3. Run the optimizer:\n   ```bash\n   image-lite\n   ```\n\n## Usage\n\n```bash\nimage-lite [options]\n\nOptions:\n  --force              Force reprocess all images, ignoring timestamps\n  --pull-lfs           Automatically pull Git LFS files\n  --no-thumbnails      Skip thumbnail generation\n  --continue-on-error  Continue processing even if some images fail\n  --resume             Resume from previous state (if interrupted)\n  --quiet, -q          Suppress non-error output\n  --watch              Watch for file changes and process automatically\n  --max-retries=N      Maximum retry attempts for failed images (default: 3)\n  --retry-delay=MS     Delay between retries in milliseconds (default: 1000)\n  --error-log=PATH     Path to error log file (default: image-lite-errors.log)\n  --help, -h           Show help message\n```\n\n### Examples\n\n```bash\n# Process all new/modified images\nimage-lite\n\n# Force reprocess all images\nimage-lite --force\n\n# Watch for changes\nimage-lite --watch\n\n# Continue on errors and log them\nimage-lite --continue-on-error --error-log=errors.log\n```\n\n## Configuration\n\nCreate a `.imagerc` or `.imagerc.json` file in your project root:\n\n```json\n{\n  \"outputDir\": \"optimized\",\n  \"formats\": [\"original\", \"webp\", \"avif\"],\n  \"generateThumbnails\": true,\n  \"thumbnailWidth\": 300,\n  \"preserveMetadata\": false,\n  \"quality\": {\n    \"jpeg\": 85,\n    \"webp\": 85,\n    \"avif\": 80,\n    \"png\": 90\n  },\n  \"qualityRules\": [\n    {\n      \"pattern\": \"**/hero-*.{jpg,png}\",\n      \"quality\": { \"jpeg\": 95, \"webp\": 95 }\n    },\n    {\n      \"pattern\": \"**/thumbnail-*.{jpg,png}\",\n      \"quality\": { \"jpeg\": 70, \"webp\": 70 }\n    }\n  ]\n}\n```\n\n### Configuration Options\n\n- **outputDir** - Output directory for optimized images (default: \"optimized\")\n- **formats** - Array of output formats: \"original\", \"webp\", \"avif\" (default: all)\n- **generateThumbnails** - Generate thumbnail versions (default: true)\n- **thumbnailWidth** - Maximum thumbnail width in pixels (default: 300)\n- **preserveMetadata** - Keep EXIF data (default: false)\n- **quality** - Default quality settings per format (1-100)\n- **qualityRules** - Per-pattern quality overrides\n\n### Quality Rules\n\nApply different quality settings based on file patterns:\n\n```json\n{\n  \"qualityRules\": [\n    {\n      \"pattern\": \"backgrounds/*.jpg\",\n      \"quality\": { \"jpeg\": 75, \"webp\": 75 }\n    },\n    {\n      \"pattern\": \"logos/*.png\",\n      \"quality\": { \"png\": 100, \"webp\": 95 }\n    },\n    {\n      \"pattern\": \"**/print-*.{jpg,png}\",\n      \"quality\": { \"jpeg\": 100, \"webp\": 100 }\n    }\n  ]\n}\n```\n\n## Docker Usage\n\nFor isolated environments or CI/CD pipelines:\n\n```bash\n# Build the Docker image\ndocker compose build\n\n# Run optimization\ndocker compose run --rm optimize\n\n# Watch mode\ndocker compose run --rm optimize-watch\n\n# With Git LFS support\ndocker compose run --rm optimize-lfs\n```\n\n## API Usage\n\n### Single File Processing\n\nOptimize individual images with a simple API:\n\n```javascript\nconst { optimizeImage, getImageMetadata } = require('image-lite');\n\n// Basic usage\nconst result = await optimizeImage(\n  'input/photo.jpg',\n  'output/photo.webp'\n);\n\n// With options\nconst result = await optimizeImage(\n  'input/photo.jpg',\n  'output/photo-optimized.jpg',\n  {\n    quality: 90,\n    resize: { width: 1920, height: 1080 },\n    preserveMetadata: false\n  }\n);\n\n// Get image info without processing\nconst metadata = await getImageMetadata('input/photo.jpg');\nconsole.log(metadata); // { width, height, format, size, ... }\n```\n\n### Batch Processing\n\nFor processing entire directories:\n\n```javascript\nconst { ImageLiteApp } = require('image-lite');\n\nasync function optimizeImages() {\n  const app = new ImageLiteApp({\n    config: {\n      outputDir: 'dist/images',\n      formats: ['webp', 'original'],\n      quality: { webp: 90 }\n    },\n    inputDir: 'src/images'\n  });\n\n  const stats = await app.processImages({\n    forceReprocess: false,\n    continueOnError: true\n  });\n\n  console.log(`Processed ${stats.processed} images`);\n}\n```\n\n## Performance Tips\n\n1. **Use WebP/AVIF** - Modern formats provide 25-50% better compression\n2. **Adjust Quality** - 85% quality is usually indistinguishable from 100%\n3. **Skip Metadata** - Removing EXIF data saves space\n4. **Batch Processing** - Process images in bulk for better performance\n5. **Use Patterns** - Apply appropriate quality based on image purpose\n\n## Error Handling\n\nimage-lite includes robust error handling:\n\n- **Automatic Retries** - Transient errors are retried with exponential backoff\n- **Error Logging** - Detailed error logs with timestamps and file paths\n- **Resume Capability** - Interrupt and resume large batch jobs\n- **Graceful Degradation** - Continue processing other images on errors\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT © J Kirby Ross\n\n## Acknowledgments\n\nBuilt with [Sharp](https://sharp.pixelplumbing.com/) - High performance Node.js image processing","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflyingrobots%2Fimage-lite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflyingrobots%2Fimage-lite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflyingrobots%2Fimage-lite/lists"}