Small Pics for Craft CMS

Why use an external image service with Craft CMS?

Craft's built-in image transforms run on your web server. Every resize, crop, and format conversion consumes CPU and memory on the same machine serving your pages. On a busy site, transform jobs compete with page requests. During deployments or cache clears, your server regenerates every transform variant from scratch.

An external image service offloads that work entirely. Images are transformed on the fly at the edge, cached globally, and served from locations close to your visitors. Your Craft server handles what it does best: content management and page rendering. The result is faster page loads, lower server costs, and no more waiting for transform queues to clear.

How does Small Pics integrate with Craft CMS?

Small Pics integrates with Craft CMS through the Imager X transformer plugin. Imager X is the standard image manipulation plugin for Craft, and Small Pics provides a dedicated transformer that plugs directly into it.

After installing the Small Pics transformer via Composer, you configure your Small Pics source URL in the Imager X settings. From that point, all Imager X transform calls in your Twig templates use Small Pics for processing. The syntax stays the same:

{% set transformed = craft.imager.transformImage(image, { width: 800, format: 'avif' }) %}

Behind the scenes, Imager X builds a Small Pics URL with the appropriate transform parameters. The image is processed on the fly, cached at the edge, and served in the requested format. Your templates do not need to know anything about the underlying service.

Small Pics also ships a PHP package for Craft developers who want lower-level control or are building custom modules. Both integration paths are documented in the setup guide.

How do you migrate from Imgix to Small Pics in Craft?

If your Craft site currently uses Imgix (either directly or through the Imager X Imgix transformer), migration takes three steps:

1. Create a Small Pics source pointing to the same origin storage your Imgix source uses (S3, R2, or any HTTP endpoint).
2. Enable Imgix compatibility on the source in the Small Pics dashboard. This tells Small Pics to accept Imgix URL parameters and translate them automatically.
3. Update your Craft config. If using Imager X, swap the transformer from Imgix to Small Pics. If using direct URLs, update your DNS or CDN origin to point to Small Pics.

With Imgix compatibility enabled, existing URLs with parameters like w, h, fit, crop, fm, and q work without changes. No template rewrites. The full parameter mapping is at /docs/imgix-compatibility.

For a detailed walkthrough, see Migrating from Imgix to Small Pics with Imager X.

Can you use Small Pics without Imager X?

Yes. Small Pics is a URL-based image transform service. You can construct transform URLs directly in your Twig templates without any plugin:

<img src="https://images.yoursite.com/photos/hero.jpg?w=1200&h=630&fit=cover&fm=avif" />

This approach works with any Craft site regardless of which plugins you have installed. Imager X is recommended because it provides a cleaner API, handles responsive srcset generation, and abstracts away the URL construction. But if you prefer to keep your stack minimal, direct URL construction works fine.

For more on the URL API, see Small Pics URL API: a practical guide.

What formats does Small Pics support?

Small Pics supports seven output formats: AVIF (default), WebP, JPEG, Progressive JPEG, PNG, GIF, and JPEG XL. AVIF is served by default with automatic format negotiation. If the browser does not support AVIF, Small Pics falls back to WebP, then JPEG.

JPEG XL is notable because very few image transform services support it (Small Pics and Gumlet are the main ones). JPEG XL delivers better compression than WebP with features like progressive decoding and lossless recompression of existing JPEGs. Browser support is growing, and you can start serving it today.

In Imager X, you specify the format in your transform call. Small Pics handles the encoding and content negotiation. Your origin images can be in any common format (JPEG, PNG, WebP, GIF) and Small Pics converts on the fly.

See also: Imgix compatibility docs, Adding image transforms to Craft CMS, Migrating from Imgix with Imager X, Pricing.