Best Practices#

Learn how to use the Image Transform API effectively for optimal performance and user experience.

Performance Optimization#

Use Format Auto-Selection#

Let the system choose the optimal format based on browser capabilities:

Benefits:

• AVIF for supporting browsers (best compression)
• WebP for most modern browsers
• JPEG/PNG for legacy browsers

Leverage DPR for High-Resolution Displays#

Always set appropriate DPR for crisp images on Retina and high-DPI screens:

Recommended values:

• Desktop: dpr:2.0
• Mobile standard: dpr:2.0
• Mobile high-end: dpr:3.0

Optimize Quality Settings#

Balance quality and file size:

CDN & Caching#

Maintain URL Consistency#

Transformed images are cached by URL. Keep URLs consistent for maximum cache efficiency:

❌ Poor practice:

?transform=w:800,h:600,quality:85
?transform=quality:85,w:800,h:600  // Different URL, same result

✅ Best practice:

?transform=w:800,h:600,quality:85  // Always use same parameter order

Leverage CDN Caching#

• First request: Transform and cache (slower)
• Subsequent requests: Instant delivery from cache
• Cache duration: 1 year

Responsive Images#

Mobile Optimization#

Considerations:

• Use smaller dimensions for mobile
• Higher DPR (3.0) for modern smartphones
• Auto format selection for bandwidth savings

Desktop Optimization#

Considerations:

• Larger dimensions for desktop displays
• Standard DPR (2.0) for most screens
• WebP for modern browsers

Use Picture Element for Art Direction#

<picture>
  <source
    media="(min-width: 768px)"
    srcset="https://cdn.snapkit.studio/org/image.jpg?transform=w:1200,dpr:2,format:auto"
  />
  <img
    src="https://cdn.snapkit.studio/org/image.jpg?transform=w:375,dpr:3,format:auto"
    alt="Responsive image"
  />
</picture>

Image Sizing Guidelines#

Don't Request Larger Than Original#

Avoid upscaling images larger than their source:

❌ Poor practice:

Original: 800x600
Request: ?transform=w:2000  // Upscaling degrades quality

✅ Best practice:

Original: 800x600
Request: ?transform=w:800   // At or below original size

Use Appropriate Dimensions#

Security & Validation#

Sanitize User Input#

Always validate and sanitize parameters from user input:

const validateWidth = (width: number): number => {
  const w = Math.floor(width);
  if (w < 1 || w > 16384) {
    throw new Error('Width must be between 1 and 16384');
  }
  return w;
};
 
const createTransformUrl = (base: string, width: number) => {
  const validWidth = validateWidth(width);
  return `${base}?transform=w:${validWidth}`;
};

Common Mistakes to Avoid#

1. Excessive DPR#

❌ Don't do this:

?transform=w:200,dpr:4.0  // 800px actual size for small thumbnail

✅ Do this instead:

?transform=w:200,dpr:2.0  // 400px is sufficient for thumbnails

2. Too Many Transformations#

❌ Avoid:

?transform=w:800,h:600,rotation:45,blur:10,grayscale,flip,flop
// Complex transforms increase processing time

✅ Keep it simple:

?transform=w:800,h:600,fit:cover
// Only necessary transformations

3. Not Using Auto Format#

❌ Static format:

?transform=w:800,format:jpeg
// Misses modern format benefits

✅ Auto format:

?transform=w:800,format:auto
// Optimal format per browser

Accessibility#

Always Provide Alt Text#

<img
  src="https://cdn.snapkit.studio/org/image.jpg?transform=w:800"
  alt="Descriptive alt text"
/>

Use Meaningful Filenames#

✅ product-blue-sneakers.jpg?transform=w:800
❌ img123.jpg?transform=w:800

Performance Checklist#

• ✅ Use format:auto for optimal format selection
• ✅ Set appropriate DPR (2.0-3.0)
• ✅ Optimize quality (75-85 for web)
• ✅ Request appropriate dimensions
• ✅ Never upscale images
• ✅ Maintain URL consistency for caching
• ✅ Validate user input
• ✅ Provide alt text
• ✅ Use srcset for responsive images

Next Steps#

• Use Cases - See real-world examples
• Limitations - Understand system limits