PHPackages                             spacecatninja/imager-x-aws-serverless-transformer - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. spacecatninja/imager-x-aws-serverless-transformer

ActiveCraft-plugin[Image & Media](/categories/media)

spacecatninja/imager-x-aws-serverless-transformer
=================================================

AWS Serverless Image Handler transformer for Imager X

3.0.2(2y ago)220.2k↓15.2%3[1 issues](https://github.com/spacecatninja/craft-imager-x-aws-serverless-transformer/issues)[1 PRs](https://github.com/spacecatninja/craft-imager-x-aws-serverless-transformer/pulls)MITPHPPHP ^8.2

Since Oct 11Pushed 2y ago1 watchersCompare

[ Source](https://github.com/spacecatninja/craft-imager-x-aws-serverless-transformer)[ Packagist](https://packagist.org/packages/spacecatninja/imager-x-aws-serverless-transformer)[ RSS](/packages/spacecatninja-imager-x-aws-serverless-transformer/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (2)Versions (12)Used By (0)

AWS Serverless Image Handler transformer for Imager X
=====================================================

[](#aws-serverless-image-handler-transformer-for-imager-x)

A plugin for using AWS Serverless Image Handler as a transformer in Imager X.
Also, an example of [how to make a custom transformer for Imager X](https://imager-x.spacecat.ninja/extending.html#transformers).

Requirements
------------

[](#requirements)

This plugin requires Craft CMS 5.0.0-beta.1 or later, [Imager X 5.0.0-beta.1](https://github.com/spacecatninja/craft-imager-x/) or later, and a working [AWS Serverless Image Handler](https://aws.amazon.com/solutions/implementations/serverless-image-handler/) setup.

Usage
-----

[](#usage)

First of all, you need to set up an [AWS Serverless Image Handler](https://aws.amazon.com/solutions/implementations/serverless-image-handler/)in AWS. If you need help and pointers, Andrew Welch has [a thorough blog post about it](https://nystudio107.com/blog/setting-up-your-own-image-transform-service).

Next, install and configure this transformer as described below. Then, in your [Imager X config](https://imager-x.spacecat.ninja/configuration.html), set the transformer to `awsserverless`, ie:

```
'transformer' => 'awsserverless',

```

Transforms are now by default transformed with the AWS Serverless Image Handler. Test your configuration with a simple transform like this:

```
{% set transform = craft.imagerx.transformImage(asset, { width: 600 }) %}

URL is: {{ transform.url }}

```

If this doesn't work, make sure the distribution URL is correct, and that the image handler is set up to use the same buckets that you assets are on.

### Cave-ats, shortcomings, and tips

[](#cave-ats-shortcomings-and-tips)

This transformer only supports a subset of what Imager X can do when using the default `craft` transformer. All the basic transform parameters are supported, with the following exceptions:

- Percentage based focal points are not supported by the image handler, it only supports edge-based positions like `left top`, `right center`, etc. Craft focal points are automatically converted to the nearest possible position.
- Only assets that are stored in AWS buckets are possible to transform.
- The `cropOnly` resize mode is not supported.
- The `cropZoom` transform parameter is not supported.
- The `frames` and `preEffects` are not relevant and supported.
- The following `effects` are converted and supported: `grayscale`, `negative`, `normalize`, `sharpen` and `blur`.
- The URL that comes from the image handler is... not pretty.

To pass additional options that is understood by the underlying sharp.js library the Serverless Image Handler uses, you can use the `transformerParams` transform parameter. Example:

```
{% set transforms = craft.imagerx.transformImage(asset,
    [{width: 400}, {width: 600}, {width: 800}],
    { ratio: 2/1, transformerParams: { tint: '#ff0066' } }
) %}

```

You can also override the automatic converted parameters, like `toFormat` and `resize`, if you need to:

```
{% set transforms = craft.imagerx.transformImage(asset,
    [{width: 400}, {width: 600}, {width: 800}],
    { ratio: 2/1, transformerParams: { tint: '#ff0066', toFormat: 'png', resize: { position: 'left top' } } }
) %}

```

For more information, check out the [sharp.js documentation](https://sharp.pixelplumbing.com/).

Installation
------------

[](#installation)

To install the plugin, follow these instructions:

1. Install with composer via `composer require spacecatninja/imager-x-aws-serverless-transformer` from your project directory.
2. Install the plugin in the Craft Control Panel under Settings > Plugins, or from the command line via `./craft plugin/install imager-x-aws-serverless-transformer`.

Configuration
-------------

[](#configuration)

You can configure the transformer by creating a file in your config folder called `imager-x-aws-serverless-transformer.php`, and override settings as needed.

### distributionUrl \[string\] (required)

[](#distributionurl-string-required)

Default: `'distributionUrl'`
This is the URL to your AWS Serverless Image Handler distribution. Example:

```
'distributionUrl' => 'https://dg5e6u1m25arf.cloudfront.net',

```

### autoConvertGif \[bool\]

[](#autoconvertgif-bool)

Default: `true`
The AWS Image Handler can't output GIF. With this setting set to `true` (default), the transformer will automatically convert GIF images to PNG to avoid errors. If you manually would like to override this at the template level (by explicitly setting `format`), you can disable this.

### defaultBucket \[string\]

[](#defaultbucket-string)

Default: `''`
By default, Imager will try to get the bucket name of the AWS volume for the asset you're trying to transform, and send that to the image handler so that it knows where to get the image from. You can configure the default bucket it should fall back to with this setting. Probably not needed, but you never know.

*Make sure you add all the buckets you've set up Craft to use, when you set up your Image Handler in AWS.*

### signatureKey \[string\]

[](#signaturekey-string)

Default: `''`
The AWS Image Handler supports using [signed URLs](https://docs.aws.amazon.com/solutions/latest/serverless-image-handler/considerations.html#image-url-signature)to prevent third parties from generating their own transforms. Once you’ve configured the image handler to use them, add your signing key and generated URLs will include a `?signature=` param that’s properly hashed and ready to go.

Be careful with this! Once enabled on the server side, any transform URL without a valid signature will return an error.

Price, license and support
--------------------------

[](#price-license-and-support)

The plugin is released under the MIT license. It requires Imager X, which is a commercial plugin [available in the Craft plugin store](https://plugins.craftcms.com/imager-x). If you need help, or found a bug, please post an issue in this repo, or in Imager X' repo.

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance10

Infrequent updates — may be unmaintained

Popularity31

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity73

Established project with proven stability

 Bus Factor1

Top contributor holds 71.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~144 days

Recently: every ~19 days

Total

10

Last Release

749d ago

Major Versions

v1.x-dev → 2.0.0-beta.12022-04-27

2.1.0 → 3.0.02024-02-11

v2.x-dev → 3.0.22024-04-29

PHP version history (2 changes)2.0.0-beta.1PHP ^8.0

3.0.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/806fbb515be53ddbca1d658f1abe7f8ddd41d77b72eec8aa85800db3a03e7e35?d=identicon)[spacecatninja](/maintainers/spacecatninja)

---

Top Contributors

[![aelvan](https://avatars.githubusercontent.com/u/2675644?v=4)](https://github.com/aelvan "aelvan (10 commits)")[![chadwells](https://avatars.githubusercontent.com/u/7211456?v=4)](https://github.com/chadwells "chadwells (2 commits)")[![mattstein](https://avatars.githubusercontent.com/u/2488775?v=4)](https://github.com/mattstein "mattstein (1 commits)")[![samuelbirch](https://avatars.githubusercontent.com/u/13586?v=4)](https://github.com/samuelbirch "samuelbirch (1 commits)")

---

Tags

awsimagecmstransformresponsiveCraftcraftcmscraft-pluginpicturesrcsetserverless

### Embed Badge

![Health badge](/badges/spacecatninja-imager-x-aws-serverless-transformer/health.svg)

```
[![Health](https://phpackages.com/badges/spacecatninja-imager-x-aws-serverless-transformer/health.svg)](https://phpackages.com/packages/spacecatninja-imager-x-aws-serverless-transformer)
```

###  Alternatives

[spacecatninja/imager-x

Ninja powered image transforms.

29390.0k23](/packages/spacecatninja-imager-x)[nystudio107/craft-imageoptimize

Automatically create & optimize responsive image transforms, using either native Craft transforms or a service like imgix, with zero template changes.

232337.2k16](/packages/nystudio107-craft-imageoptimize)[nystudio107/craft-youtubeliveembed

This plugin allows you to embed a YouTube live stream and/or live chat on your webpage

163.7k](/packages/nystudio107-craft-youtubeliveembed)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)