lazy-image 🦀

Web image optimization engine for Node.js. Rust core, smaller outputs than sharp.

lazy-image reduces image file sizes by 20-30% compared to sharp, trading encoding speed for smaller outputs. Ideal for CDN-heavy workloads where bandwidth costs matter more than CPU costs.

• Not a drop-in replacement for sharp — use sharp if you need its full API or maximum throughput.
• Security-first: Metadata stripped by default; keepMetadata() to preserve. Zero-copy path: fromPath()/processBatch() → toFile().
• Japanese: README.ja.md. mmap: Do not modify/delete source files while processing; use a copy or from(Buffer) for mutable inputs.

Quick Start (5 lines)

const { ImageEngine } = require('@alberteinshutoin/lazy-image');

const bytesWritten = await ImageEngine.fromPath('input.png')
  .resize(800)
  .toFile('output.jpg', 'jpeg', 80);

console.log(`Wrote ${bytesWritten} bytes`);

Choose lazy-image if / Choose sharp if

| Choose lazy-image if | Choose sharp if | |---|---| | You pay for bandwidth (CDN, S3, CloudFront) | You need maximum encoding throughput | | You run in serverless / memory-constrained envs | You need a broad image editing API | | You want AVIF with good defaults | You need drop-in API compatibility | | You want smaller outputs over faster encodes | You need GIF, SVG, or TIFF support |

Key differentiators:

1. File size optimization — mozjpeg + libwebp + ravif produce 20-30% smaller outputs than sharp's defaults
2. Memory efficiency — zero-copy mmap architecture; no pixel data copied to the JS heap
3. Security-first — GPS auto-strip, Image Firewall, Rust memory safety
4. AVIF excellence — ravif encoder with quality-optimized defaults

What lazy-image does NOT compete on: raw encoding speed (sharp/libvips is faster), feature breadth (no drawing, compositing, or GIF), API compatibility with sharp.

Benchmarks and details: docs/PERFORMANCE.md. Full compatibility matrix: docs/COMPATIBILITY.md.

Cost Savings Example (ROI)

Assume:

• average image size before optimization: 1.0 MB
• average reduction with lazy-image: 25%
• CDN transfer rate: $0.085/GB (example: CloudFront pay-as-you-go, US/EU next 9TB tier)

| Scenario | Transfer with sharp | Transfer with lazy-image | Monthly savings | |---|---:|---:|---:| | 1M image deliveries / month | 976.6 GB | 732.4 GB | $20.75 | | 10M image deliveries / month | 9.54 TB | 7.15 TB | $207.52 | | 100M image deliveries / month | 95.37 TB | 71.53 TB | $2,075.20 |

Break-even intuition:

• Encoding overhead is paid once per generated image
• Bandwidth savings are realized every time the image is delivered
• If each generated image is viewed multiple times, lazy-image generally wins quickly

Use the interactive calculator:

• docs/roi-calculator.html
• Methodology and formulas: docs/ROI_CALCULATOR.md

Installation

npm install @alberteinshutoin/lazy-image

Platform-specific binaries (~6–9 MB per platform) are installed automatically. Build from source: npm run build. See docs/PERFORMANCE.md for package size comparison with sharp.

Basic Usage

Resize and save (recommended: file-to-file)

await ImageEngine.fromPath('photo.jpg')
  .resize({ width: 800, fit: 'inside' }) // positional args also supported
  .toFile('thumb.jpg', 'jpeg', 85);

Format conversion (e.g. PNG → WebP/AVIF)

const buffer = await ImageEngine.fromPath('input.png')
  .resize({ width: 600 })
  .toBuffer('webp', 80);

Metadata without decoding

const { inspectFile } = require('@alberteinshutoin/lazy-image');
const meta = inspectFile('input.jpg'); // { width, height, format }

More: batch processing, presets, metrics, streaming — docs/API.md.

Documentation

| Topic | Link | |-------|------| | Full API reference | docs/API.md | | Migration from sharp | docs/MIGRATION_FROM_SHARP.md | | Performance & when to use | docs/PERFORMANCE.md | | Architecture & security | docs/ARCHITECTURE.md | | Troubleshooting | docs/TROUBLESHOOTING.md | | Security policy & reporting | SECURITY.md | | Roadmap & scope | docs/ROADMAP.md | | ROI calculator methodology | docs/ROI_CALCULATOR.md | | Version history | docs/VERSION_HISTORY.md | | Specification (spec/) | spec/pipeline.md, spec/resize.md, spec/errors.md, spec/limits.md, spec/quality.md, spec/metadata.md | | Error codes | docs/ERROR_CODES.md | | Benchmarks (raw data) | docs/TRUE_BENCHMARKS.md | | Binary size comparison (AVIF on/off) | docs/BINARY_SIZE.md | | Benchmark snapshots log | docs/BENCHMARK_RESULTS.md | | Benchmark operations | docs/BENCHMARK_OPERATIONS.md |

Features (summary)

Smaller JPEG (mozjpeg) · Smaller WebP (libwebp) · AVIF (ravif) · ICC profiles (AVIF in v0.9.x) · EXIF auto-orient · Zero-copy file I/O · Bounded-memory streaming · Image Firewall · GPS auto-strip · Fluent API · Rust core (NAPI-RS) · Cross-platform (macOS, Windows, Linux). Design choices and limits: docs/ROADMAP.md and docs/ARCHITECTURE.md.

Development

npm install && npm run build
npm test

See CLAUDE.md for workflow, test commands, and CI. Benchmark testing: lazy-image-test Docker environment. Fuzzing: FUZZING.md.

License

MIT

Credits

mozjpeg · libwebp · ravif · fast_image_resize · img-parts · napi-rs

Ship it. 🚀