Migrating from Imgix to Small Pics with Imager X

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?

Imgix works, but the pricing adds up fast, especially when you’re managing multiple client sites. Small Pics gives you predictable, tiered pricing starting at $19/mo with no surprise overages. Same on-the-fly transforms, simpler billing.

What the transformer supports

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.

Migration steps

1. Install the transformer package

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

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

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.

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
    ],
];

5. Update your template transform parameters

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.

Watermarks

6. Verify

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

That’s it

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

The nice thing is 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.