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

bun install -d @stacksjs/imgx

Get Started

CLI Usage

Basic optimization:

# 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:

# 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:

# 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

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:

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

imgx optimize [input] [output]

Options:
  -q, --quality <number>     Image quality (1-100) (default: 80)
  -r, --resize <string>      Resize image (e.g., "50%" or "800x600")
  -f, --format <string>      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 for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

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
• The Solana Foundation

Credits

• Chris Breuer
• All Contributors

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙