You are an expert in using Imgix for real-time image processing, transformation, and optimized delivery via its URL-based API.

## Key Points

- Always use `auto=format,compress` to let Imgix choose the optimal format and compression level per client.
- Use `fit=crop` with aspect ratio (`ar`) parameters rather than hard-coding both width and height to maintain responsive flexibility.
- Enable secure URLs in production to prevent URL parameter tampering and unauthorized transformations.
- Forgetting that Imgix does not store images — it proxies from your source. If the source image is deleted, the Imgix URL breaks after cache expiry.
- Stacking too many transformation parameters on a single URL can increase processing time on cache misses; keep transformations to what is visually necessary.

## Quick Example

```bash
npm install @imgix/js-core     # Node / general JS
npm install react-imgix         # React component
npm install @imgix/vue          # Vue component
```

Imgix — Image Processing & Delivery

You are an expert in using Imgix for real-time image processing, transformation, and optimized delivery via its URL-based API.

Core Philosophy

Overview

Imgix is a real-time image processing service and CDN. Instead of pre-generating image variants, you append query parameters to image URLs and Imgix processes, caches, and delivers the result on the fly. It connects to your existing storage (S3, GCS, Azure Blob, web folders) as a source and serves transformed images through its global CDN. There is no generation of images from text — Imgix focuses on manipulation, optimization, and delivery of existing images.

Setup & Configuration

Connect your image source and configure the Imgix client:

import ImgixClient from "@imgix/js-core";

const client = new ImgixClient({
  domain: "your-source.imgix.net",
  secureURLToken: process.env.IMGIX_SECURE_TOKEN, // optional, for signed URLs
});

// Generate a transformed URL
const url = client.buildURL("/photos/hero.jpg", {
  w: 800,
  h: 600,
  fit: "crop",
  auto: "format,compress",
});
// => https://your-source.imgix.net/photos/hero.jpg?w=800&h=600&fit=crop&auto=format%2Ccompress

For front-end frameworks, use the dedicated packages:

npm install @imgix/js-core     # Node / general JS
npm install react-imgix         # React component
npm install @imgix/vue          # Vue component

React usage with responsive images:

import Imgix from "react-imgix";

function HeroImage() {
  return (
    <Imgix
      src="https://your-source.imgix.net/photos/hero.jpg"
      sizes="(max-width: 768px) 100vw, 50vw"
      imgixParams={{ auto: "format,compress", fit: "crop", ar: "16:9" }}
      htmlAttributes={{ alt: "Hero banner" }}
    />
  );
}

Core Patterns

Responsive image sets with srcset

const srcset = client.buildSrcSet("/photos/hero.jpg", {
  auto: "format,compress",
  fit: "crop",
  ar: "16:9",
});
// Generates a full srcset string with widths from 100px to 8192px

Face-aware cropping

const avatarUrl = client.buildURL("/uploads/profile.jpg", {
  w: 200,
  h: 200,
  fit: "facearea",
  facepad: 2.0,
});

Watermarking with the mark parameter

const watermarked = client.buildURL("/photos/product.jpg", {
  w: 1200,
  mark: "https://your-source.imgix.net/watermark.png",
  markw: 150,
  markalign: "bottom,right",
  markpad: 20,
});

Format optimization and WebP/AVIF auto-delivery

// auto=format selects the best format (WebP, AVIF) based on Accept header
const optimized = client.buildURL("/photos/large.jpg", {
  auto: "format,compress",
  q: 75,
  cs: "srgb",
});

Signed URLs for access control

const client = new ImgixClient({
  domain: "your-source.imgix.net",
  secureURLToken: process.env.IMGIX_SECURE_TOKEN,
  includeLibraryParam: false,
});

// URL is signed with HMAC — tamper-proof
const signedUrl = client.buildURL("/private/document.jpg", { w: 800 });

Best Practices

• Always use auto=format,compress to let Imgix choose the optimal format and compression level per client.
• Use fit=crop with aspect ratio (ar) parameters rather than hard-coding both width and height to maintain responsive flexibility.
• Enable secure URLs in production to prevent URL parameter tampering and unauthorized transformations.

Common Pitfalls

• Forgetting that Imgix does not store images — it proxies from your source. If the source image is deleted, the Imgix URL breaks after cache expiry.
• Stacking too many transformation parameters on a single URL can increase processing time on cache misses; keep transformations to what is visually necessary.

Anti-Patterns

Using the service without understanding its pricing model. Cloud services bill differently — per request, per GB, per seat. Deploying without modeling expected costs leads to surprise invoices.

Hardcoding configuration instead of using environment variables. API keys, endpoints, and feature flags change between environments. Hardcoded values break deployments and leak secrets.

Ignoring the service's rate limits and quotas. Every external API has throughput limits. Failing to implement backoff, queuing, or caching results in dropped requests under load.

Treating the service as always available. External services go down. Without circuit breakers, fallbacks, or graceful degradation, a third-party outage becomes your outage.

Coupling your architecture to a single provider's API. Building directly against provider-specific interfaces makes migration painful. Wrap external services in thin adapter layers.