Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/stacksjs/imgx
🏞️ Make your images load faster. A better save for the web.
https://github.com/stacksjs/imgx
avif bun gif image imageoptim imgix jpeg optimizing png processing sharp svg typescript web webp
Last synced: about 4 hours ago
JSON representation
🏞️ Make your images load faster. A better save for the web.
- Host: GitHub
- URL: https://github.com/stacksjs/imgx
- Owner: stacksjs
- License: mit
- Created: 2025-01-25T18:09:44.000Z (9 days ago)
- Default Branch: main
- Last Pushed: 2025-02-02T23:28:07.000Z (about 14 hours ago)
- Last Synced: 2025-02-03T00:24:57.994Z (about 13 hours ago)
- Topics: avif, bun, gif, image, imageoptim, imgix, jpeg, optimizing, png, processing, sharp, svg, typescript, web, webp
- Language: TypeScript
- Homepage: https://imgx.netlify.app
- Size: 479 KB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
[![npm version][npm-version-src]][npm-version-href]
[![GitHub Actions][github-actions-src]][github-actions-href]
[](http://commitizen.github.io/cz-cli/)
# imgx
> A powerful image optimization toolkit for modern web development.
## Features
- **Advanced Image Optimization**
- Lossy & lossless compression
- Smart quality optimization
- Metadata stripping
- Color profile management
- **Format Support**
- WebP, AVIF conversion
- JPEG, PNG optimization
- SVG minification
- Animated GIF optimization
- **Modern Web Features**
- Responsive image generation
- Art direction support
- Lazy loading helpers
- ThumbHash placeholders
- Sprite sheet generation
- OG Image generation
- **Developer Experience**
- Watch mode for development
- Development server with on-the-fly optimization
- CI/CD integration
- Detailed analysis and reporting
- Progress indicators
- **Privacy & Performance**
- Metadata stripping
- Configurable optimization levels
- Cache control
- Web-optimized by default
## Install
```bash
bun install -d @stacksjs/imgx
```
## Get Started
### CLI Usage
Basic optimization:
```bash
# Optimize a single image
imgx optimize input.jpg -q 75
# Convert to WebP
imgx optimize input.jpg output.webp -f webp
# Optimize a directory of images
imgx optimize ./images -R -f webp
# Watch mode for development
imgx optimize ./src/images -w -f webp
```
Advanced features:
```bash
# Generate responsive images
imgx optimize hero.jpg --responsive --responsive-sizes 320,768,1024,1920
# Create sprite sheet
imgx sprite ./icons ./dist --retina --optimize
# Generate thumbnails with ThumbHash
imgx optimize input.jpg -t --thumbhash-size 64x64
# Analyze image optimization potential
imgx analyze ./images -o report.json --ci
```
Development server:
```bash
# Start dev server with on-the-fly optimization
imgx serve ./public -p 3000
# Access optimized images:
# http://localhost:3000/image.jpg?format=webp&quality=75&size=800x600
```
### Library Usage
```ts
import { process, generateSprite, analyzeImage } from '@stacksjs/imgx'
// Basic optimization
await process({
input: 'input.jpg',
output: 'output.webp',
quality: 75,
format: 'webp'
})
// Generate responsive images
await process({
input: 'hero.jpg',
responsive: true,
responsiveSizes: [320, 768, 1024, 1920],
format: 'webp'
})
// Create sprite sheet
await generateSprite({
images: ['icon1.png', 'icon2.png'],
output: './dist',
retina: true,
format: 'webp'
})
// Analyze images
const report = await analyzeImage('image.jpg')
console.log(report.optimizationPotential)
```
## Configuration
Create an `imgx.config.ts` file:
```ts
import type { ImgxConfig } from '@stacksjs/imgx'
export default {
// General options
verbose: true,
cache: true,
cacheDir: '.imgx-cache',
// Default optimization settings
quality: 75,
format: 'webp',
progressive: true,
stripMetadata: true,
// Responsive image settings
responsive: {
sizes: [320, 768, 1024, 1920],
formats: ['webp', 'avif'],
quality: 75
},
// Sprite generation
sprites: {
retina: true,
padding: 2,
prefix: 'icon',
format: 'webp'
},
// Development server
server: {
port: 3000,
cache: true,
cors: true
}
} satisfies ImgxConfig
```
## CLI Reference
```bash
imgx optimize [input] [output]
Options:
-q, --quality Image quality (1-100) (default: 80)
-r, --resize Resize image (e.g., "50%" or "800x600")
-f, --format Output format (jpeg, png, webp, avif)
-p, --progressive Enable progressive mode (default: true)
-m, --preserve-metadata Preserve image metadata
-w, --watch Watch for file changes
-R, --recursive Process directories recursively
-t, --thumbhash Generate ThumbHash placeholder
--responsive Generate responsive images
--skip-existing Skip already optimized files
--backup Create backup of original files
Examples:
$ imgx optimize input.jpg -q 75 -r 50%
$ imgx optimize ./images -f webp -R
$ imgx optimize input.jpg -t --thumbhash-size 64x64
$ imgx sprite ./icons ./dist --retina --optimize
$ imgx analyze ./images --ci --threshold 500KB
```
## Contributing
Please review the [Contributing Guide](https://github.com/stacksjs/contributing) for details.
## Community
For help, discussion about best practices, or any other conversation that would benefit from being searchable:
[Discussions on GitHub](https://github.com/stacksjs/stacks/discussions)
For casual chit-chat with others using this package:
[Join the Stacks Discord Server](https://discord.gg/stacksjs)
## Postcardware
Two things are true: Stacks OSS will always stay open-source, and we do love to receive postcards from wherever Stacks is used! _We also publish them on our website._
Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094 🌍
## Sponsors
We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.
- [JetBrains](https://www.jetbrains.com/)
- [The Solana Foundation](https://solana.com/)
## Credits
- [Chris Breuer](https://github.com/chrisbbreuer)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [LICENSE](LICENSE.md) for more information.
Made with 💙
[npm-version-src]: https://img.shields.io/npm/v/@stacksjs/imgx?style=flat-square
[npm-version-href]: https://npmjs.com/package/@stacksjs/imgx
[github-actions-src]: https://img.shields.io/github/actions/workflow/status/stacksjs/imgx/ci.yml?style=flat-square&branch=main
[github-actions-href]: https://github.com/stacksjs/imgx/actions?query=workflow%3Aci