Migrating from Imgix to Small Pics with Imager X

To migrate from Imgix to Small Pics in Craft CMS, install the Small Pics Imager X transformer, update your environment variables, and rename a few transform parameters. The whole process takes under an hour.

If you’re a Craft CMS developer using Imager X with Imgix transforms, switching to Small Pics is straightforward. We’ve built a dedicated Imager X transformer that plugs directly into your existing setup. No need to rewrite your templates from scratch.

Why switch from Imgix to Small Pics?

Imgix works, but the pricing adds up fast, especially when you’re managing multiple client sites. Small Pics offers predictable, tiered pricing starting at $9/mo with no credit math. Imgix has a larger API surface (100+ operations) and a more mature ecosystem. For the core transforms most sites need (resize, crop, format, quality, watermarks), both cover the use case. The difference is billing model and migration effort.

What does the Small Pics transformer support?

The Small Pics Imager X transformer supports these native Imager X properties:

• width
• height
• format
• mode (fit maps to contain)

You can also pass any Small Pics-specific parameters via transformerParams. These use the same format described in the Small Pics PHP package docs. Focal point configs are automatically supported when mode=fit.

How do you install the Small Pics transformer?

Step 1: Install the transformer package

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

Step 2: Set environment variables

Add these to your .env file:

# Switch Imager X to the Small Pics transformer
IMAGERX_TRANSFORMER=smallpics

# Your Small Pics image source base URL
SMALLPICS_BASE_URL=https://media.myproject.com

# Optional: only needed if your image source requires signed URLs
SMALLPICS_SECRET=your-signing-secret

Step 3: Update imager-x.php config

Point the transformer to your new environment variable:

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

You can remove the imgixApiKey and imgixConfig blocks entirely. They’re no longer needed.

Step 4: Add imagerx-smallpics.php config

Create a new config file at config/imagerx-smallpics.php:

return [
    'baseUrl' => App::env('SMALLPICS_BASE_URL'),
    'secret' => App::env('SMALLPICS_SECRET'),
    'defaultParams' => [
        'format' => 'avif', // Not required, this is the Small Pics default
        'quality' => 85,    // Not required, this is the Small Pics default
    ],
];

What config changes are needed in your templates?

Update any transformImage calls to use Small Pics transform parameters instead of Imgix ones. The changes are minimal, mostly renaming parameters.

The mode, width, and height params work the same. Everything else moves into transformerParams using Small Pics-native names. See the full list of supported parameters.

How do you migrate watermarks?

Can you migrate without renaming any parameters?

Yes. If you want an even simpler migration path, Small Pics has built-in Imgix parameter compatibility that can be enabled per image source in the dashboard.

When enabled, Small Pics translates Imgix query parameters to their Small Pics equivalents server-side. Most core parameters are supported: w, h, fit, crop, fp-x, fp-y, dpr, fm, q, sharp, bri, con, gam, flip, orient, bg, border, pad, and the full set of watermark parameters.

This is especially useful for:

• Sites not using Imager X that have Imgix URLs hardcoded in templates or a CMS
• Teams that want zero-effort migration with no template changes at all
• Staging environments where you want to verify output before touching any code

Enable Imgix compatibility on your Small Pics image source, point your DNS, and your existing URLs keep working. You can always switch to native Small Pics parameters later if you want to. See the full Imgix parameter mapping for the complete list of supported parameters.

How do you verify the migration?

• View source and confirm image URLs point to your Small Pics domain
• Check that focal points and cropping behave as expected

To recap:

1. Install the transformer plugin via Composer
2. Add your Small Pics env vars
3. Point imager-x.php at the new transformer
4. Create imagerx-smallpics.php with your base URL and defaults
5. Find and replace Imgix params with their Small Pics equivalents
6. Verify your images load

Your Twig templates barely change. You’re mostly just swapping out the transformer config and tweaking a few parameter names. If you’re already on Imager X, the whole thing takes well under an hour.

Need help migrating?

We’ve migrated multiple production Craft CMS sites from Imgix to Small Pics and we’re happy to help you do the same. If you run into any issues or just want a hand with the switch, reach out to us at support@smallpics.io. We’ll walk through it with you.