Image Optimization

Improve your website performance with Stormkit’s framework-agnostic image optimization. Resize, crop, and intelligently focus images using simple URL parameters.

Overview

Stormkit includes a powerful, framework-agnostic image optimization feature that allows you to resize and crop images on-the-fly through simple URL parameters. This feature helps improve your website’s performance by delivering appropriately sized images to your users.

The image optimization service automatically processes images when specific query parameters are detected in the image URL. Optimized images are cached for improved performance on subsequent requests.

Usage

To optimize an image, simply add query parameters to your image URL:

https://your-domain.com/path/to/image.jpg?size=WIDTHxHEIGHT&smart=true|false

Parameters

Parameter	Description	Format	Example
size	Specifies the desired dimensions	WIDTHxHEIGHT or just WIDTH	size=400x300 or size=400
smart	Enables smart cropping to maintain focus on the important parts of the image	true or false	smart=true

Examples

Basic Resize

Resize maintaining aspect ratio

/images/photo.jpg?size=400

Resizes to 400px width while maintaining aspect ratio.

Specific Dimensions

Force exact dimensions

/images/photo.jpg?size=400x300

Forces image to be exactly 400px × 300px.

Smart Cropping

Intelligent focus preservation

/images/photo.jpg?size=400x300&smart=true

Crops to 400x300px while focusing on important parts.

Responsive Images

Different sizes for different devices

<picture>
  <source media="(max-width: 600px)" 
          srcset="/photo.jpg?size=600" />
  <img src="/photo.jpg?size=1200" />
</picture>

Use Cases

Responsive Images

Use different size parameters based on the user’s device to deliver appropriate images:

<picture>
  <source media="(max-width: 600px)" srcset="/images/photo.jpg?size=600" />
  <source media="(max-width: 1200px)" srcset="/images/photo.jpg?size=1200" />
  <img src="/images/photo.jpg?size=2048" alt="Description" />
</picture>

Thumbnails with Smart Cropping

When creating thumbnails or profile pictures, use smart cropping to ensure the subject remains in focus:

<img src="/images/profile.jpg?size=150x150&smart=true" alt="Profile picture" />

Gallery Optimization

<!-- Thumbnail -->
<img src="/gallery/photo1.jpg?size=200x200&smart=true" alt="Thumbnail" />

<!-- Full size view -->
<img src="/gallery/photo1.jpg?size=1200" alt="Full size" />

Security and Limitations

Important Limits:

• Maximum Dimensions: 2048px (width or height). Requests exceeding this return the original image.
• Variant Limit: Maximum of 5 optimized variants per original image to prevent storage abuse.
• Caching: Optimized images are cached for 24 hours.

Why These Limits?

• Maximum dimensions prevent abuse and ensure reasonable resource usage
• Variant limit prevents storage exhaustion from unlimited optimization requests
• Caching improves performance for subsequent requests

Additional variant requests beyond the 5-variant limit will return the original image.

Best Practices

1. Use Appropriate Sizes

Don’t request images larger than you need:

<!-- Good: Request only what you need -->
<img src="/image.jpg?size=400" alt="Image" style="max-width: 400px" />

<!-- Bad: Requesting unnecessarily large image -->
<img src="/image.jpg?size=2048" alt="Image" style="max-width: 400px" />

2. Leverage Smart Cropping

Use smart cropping for thumbnails and profile pictures:

<!-- Smart cropping keeps the subject in focus -->
<img src="/avatar.jpg?size=150x150&smart=true" alt="Avatar" />

3. Implement Responsive Images

Serve different sizes for different screen sizes:

<img 
  srcset="
    /image.jpg?size=400 400w,
    /image.jpg?size=800 800w,
    /image.jpg?size=1200 1200w
  "
  sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px"
  src="/image.jpg?size=800"
  alt="Responsive image"
/>

4. Plan Your Variants

With a 5-variant limit, choose your sizes wisely:

Original: 2400x1600
Variants:
1. Thumbnail: 200x200 (smart)
2. Mobile: 600
3. Tablet: 1024
4. Desktop: 1920
5. Square crop: 800x800 (smart)

Supported Formats

The image optimization service supports the following formats:

• JPEG - Best for photographs
• PNG - Best for graphics with transparency
• WebP - Modern format with excellent compression
• GIF - Non-animated GIFs only
• TIFF - High-quality images

Animated GIFs are not supported. The first frame will be used.

Error Handling

If an image cannot be optimized due to any reason (invalid image format, processing error, etc.), the system will return the original image without optimization.

This ensures your site never breaks due to image optimization failures.

Performance Tips

Pre-warm Cache

Request common image sizes during deployment to pre-warm the cache.

CDN Integration

Optimized images work seamlessly with CDNs for global distribution.

Lazy Loading

Combine with lazy loading for optimal page load performance.

Monitor Usage

Track which variants are actually used and adjust accordingly.

Troubleshooting

Image not resizing

• Verify the size parameter format is correct
• Check if the image format is supported
• Ensure the URL is properly encoded
• Verify the domain has optimization enabled

Getting original image instead of optimized

• Check if you’ve exceeded the 5-variant limit
• Verify dimensions don’t exceed 2048px
• Check if the image format is supported
• Review server logs for processing errors

Smart cropping not working as expected

• Ensure smart=true parameter is set
• Verify both width and height are specified
• Remember: smart cropping analyzes image content
• Try different size ratios for better results

Need Help?

If you encounter any issues with the image optimization feature, please contact Stormkit support or open an issue on our GitHub repository.