How to Add On-the-Fly Image Transforms to a Craft CMS Site

The fastest way to add on-the-fly image transforms to a Craft CMS site is to use Imager X with an external transformer like Small Pics. This offloads image processing from your server and serves optimized images from a global CDN.

This guide walks through the full setup, from installing Imager X to serving responsive AVIF images.

What are on-the-fly image transforms?

On-the-fly transforms process images at the moment they are requested. Instead of pre-generating every crop, size, and format during a build step or queue job, you request the exact image you need via a URL and the transform service returns it instantly. The result is cached at the edge for subsequent requests.

For example, this URL requests a 800x600 AVIF crop:

https://media.yoursite.com/photo.jpg?w=800&h=600&fit=cover&fm=avif

The first request triggers the transform. Every request after that is served from cache.

Why use an external image service instead of Craft’s built-in transforms?

Craft CMS has built-in image transforms, but they run on your web server. For a site with hundreds of images and multiple responsive sizes, this means:

• CPU and memory pressure on your web server during transform generation
• Slower first-page loads when transforms have not been generated yet
• No edge caching unless you configure a CDN separately
• No automatic format negotiation (you need to manually create AVIF and WebP variants)

External services like Small Pics handle all of this on dedicated infrastructure. Your Craft server only serves the CMS. Images are processed on Small Pics’ infrastructure and cached at edge locations worldwide.

The trade-off is cost: you pay for the service. But for most production sites, the performance and operational benefits outweigh the $9-59/mo.

How do you set up Imager X with Small Pics?

Step 1: Install Imager X

If you do not already have Imager X installed:

composer require spacecatninja/craft-imager-x
php craft plugin/install imager-x

Step 2: Install the Small Pics transformer

composer require smallpics/imagerx-smallpics -w
php craft plugin/install imagerx-smallpics

Step 3: Configure environment variables

Add these to your .env file:

IMAGERX_TRANSFORMER=smallpics
SMALLPICS_BASE_URL=https://media.yoursite.com
SMALLPICS_SECRET=your-signing-secret  # optional, only if using signed URLs

SMALLPICS_BASE_URL is the base URL of the Small Pics image source you configured in the Small Pics dashboard.

Step 4: Update Imager X config

Edit config/imager-x.php:

return [
    'transformer' => getenv('IMAGERX_TRANSFORMER'),
    'useForNativeTransforms' => true,
    'useForCpThumbs' => true,
];

Step 5: Create the Small Pics config

Create config/imagerx-smallpics.php:

return [
    'baseUrl' => App::env('SMALLPICS_BASE_URL'),
    'secret' => App::env('SMALLPICS_SECRET'),
    'defaultParams' => [
        'format' => 'avif',
        'quality' => 85,
    ],
];

That is the full setup. Your existing craft.imager.transformImage() calls will now route through Small Pics.

How do you configure responsive images with srcset?

Imager X makes responsive images straightforward. Define multiple widths and let Small Pics handle each transform:

{% set transforms = craft.imager.transformImage(asset, [
    { width: 400 },
    { width: 800 },
    { width: 1200 },
]) %}

<img
    src="{{ transforms[1].url }}"
    srcset="{{ craft.imager.srcset(transforms) }}"
    sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
    alt="{{ asset.title }}"
    loading="lazy"
/>

Each width generates a separate Small Pics URL. The first request for each size triggers a transform; subsequent requests are served from cache.

For retina displays, you can use the dpr parameter in transformerParams:

{% set transforms = craft.imager.transformImage(asset, [
    { width: 400, transformerParams: { dpr: 2 } },
    { width: 800, transformerParams: { dpr: 2 } },
]) %}

What image formats should you serve in 2026?

AVIF has full support in all major browsers as of 2026. It typically produces files 30-50% smaller than WebP at equivalent visual quality. Small Pics defaults to AVIF output.

For maximum compatibility, use the <picture> element with multiple sources:

{% set avif = craft.imager.transformImage(asset, { width: 1200, transformerParams: { fm: 'avif', q: 80 } }) %}
{% set webp = craft.imager.transformImage(asset, { width: 1200, transformerParams: { fm: 'webp', q: 80 } }) %}
{% set jpg = craft.imager.transformImage(asset, { width: 1200, transformerParams: { fm: 'jpg', q: 80 } }) %}

<picture>
    <source srcset="{{ avif[0].url }}" type="image/avif" />
    <source srcset="{{ webp[0].url }}" type="image/webp" />
    <img src="{{ jpg[0].url }}" alt="{{ asset.title }}" loading="lazy" />
</picture>

If you are comfortable targeting only modern browsers, serving AVIF by default (the Small Pics default) covers nearly all users.

How do you handle focal points and smart cropping?

Craft CMS lets content editors set focal points on image assets. When you use Imager X with the Small Pics transformer, focal point data is automatically passed through.

In your Twig templates, use mode: 'crop' and the focal point is respected:

{% set hero = craft.imager.transformImage(asset, {
    width: 1200,
    height: 630,
    mode: 'crop',
}) %}

If the content editor has set a focal point on the asset, the crop centers on that point. No additional configuration needed.

For manual control without Imager X, use the fit parameter with percentage-based crop positioning:

https://media.yoursite.com/photo.jpg?w=1200&h=630&fit=crop-75%-25%

This crops with the focal point at 75% from the left and 25% from the top.

What other Small Pics features should you configure?

Once you have the basic setup working, there are a few things worth exploring:

• Signed URLs protect your images from unauthorized parameter tampering. Enable signing in the Small Pics dashboard and pass your secret via SMALLPICS_SECRET.
• Instant purge lets you clear cached transforms when a content editor replaces an image. Small Pics supports this through the dashboard and API.
• Watermarks can be applied on the fly using the mark parameter. See the URL API guide for the full parameter list.

If you are migrating from Imgix specifically, Small Pics has built-in Imgix parameter compatibility that lets you keep your existing URLs without changes. Our migration guide covers both the Imager X approach and the zero-effort compatibility mode. And if you want to try it on your own site, start a free trial with no credit card required.