strapi-plugin-thumbor-image-formats v0.1.4

Strapi Plugin - Thumbor Image Formats

Custom image formats using a thumbor server to create the formats. This prevents multiple formats from being stored with the storage provider. Formats are pre-requested from the thumbor server making them available immediately.

Warning: When an image is replaced via the Strapi admin UI the file's hash will change. By default, Strapi's upload plugin keeps the file hash for image replace operations. This causes issues with thumbor's result caching, so the hash needs to be updated on replace.

Installation

Using npm

npm install --save strapi-plugin-thumbor-image-formats

Using Yarn

yarn add strapi-plugin-thumbor-image-formats

Setup

The upload and image-manipulation services of the upload plugin need to be overwritten redirecting to this plugin. You can use the installed script create-thumbor-image-formats-overrides to create these files or manually add the files upload.js and image-manipulation.js to the extensions/upload/services/ folder.

Remember to build Strapi after adding the overrides. e.g. using npm npm build or yarn yarn build

Using the script to create overrides

Use the strapi-plugin-thumbor-image-formats create-overrides command from the root directory of your strapi project.

Warning: This will replace existing files upload.js and image-manipulation.js in extensions/upload/services/.

strapi-plugin-thumbor-image-formats create-overrides

> Copying upload.js to /usr/src/app/extensions/upload/services/upload.js
> Copying image-manipulation.js to /usr/src/app/extensions/upload/services/image-manipulation.js

Manually creating overrides

Manually create upload.js in extensions/upload/services/ and paste the code below:

"use strict";

const {services} = require("strapi-plugin-thumbor-image-formats");
module.exports = services.Upload;

Manually create image-manipulation.js in extensions/upload/services/ and paste the code below:

"use strict";

const {services} = require("strapi-plugin-thumbor-image-formats");
module.exports = services.ImageManipulation;

Rebuild Strapi

After the overrides are created you'll need to rebuild strapi.

Using npm

npm run build

Using Yarn

yarn build

Configuration

Thumbor server

You need to provide a public url, private url for the thumbor server and an optional thumbor security key It is highly recommended you use HMAC security with your thumbor server.

• thumborHostPublic is the public facing url of the thumbor server, used in the formats urls.
• thumborHostPrivate is the private url used by the plugin behind the scenes to pre-fetch the formats to get their calculated height and file size. If you want your Strapi server to use the public url of the thumbor server, repeat it here.
• thumborSecurityKey is the security key used by thumbor for generating HMAC keys for image requests to prevent url tampering. Without this setting thumbor 'unsafe' urls will be used.

Thumbor configuration example:

// config/plugins.js 

module.exports = ({env}) => ({
    thumborImageFormats: {
        thumborHostPublic: 'https://thumbor.mydomain.com',
        thumborHostPrivate: 'http://server-thumbor:8000',
        // optional security key
        thumborSecurityKey: 'abcdefghijklmnopqrstuvwxyz123',
        // ...
    }
})

It's highly recommended that you store your configuration in the host environment variables.

# Host environment variables

THUMBOR_PUBLIC_URL=https://thumbor.mydomain.com
THUMBOR_PRIVATE_URL=http://server-thumbor:8000
THUMBOR_KEY=abcdefghijklmnopqrstuvwxyz123

// config/plugins.js

module.exports = ({env}) => ({
    thumborImageFormats: {
        thumborHostPublic: env('THUMBOR_PUBLIC_URL'),
        thumborHostPrivate: env('THUMBOR_PRIVATE_URL'),
        thumborSecurityKey: env('THUMBOR_KEY'),
        // ...
    }
})

Local file upload provider

If you are using a local file upload provider, like the default used by Strapi's upload plugin, you need to specify a host for thumbor to retrieve the images from. You do so by setting the localFileHost property in the plugin config. This host needs to be accessible from your thumbor server.

module.exports = ({env}) => ({
    thumborImageFormats: {
        // ...
        localFileHost: 'http://strapi.mydomain:1337',
        // ...
    }
})

Formats

By default, thumbnail and small, medium, large image formats are created in line with Strapi's default formats. However, only thumbnail and small are required for the admin to show the resized images.

If you do not use the additional formats it is recommended to overwrite the formats in the plugin configuration to reduce the amount of formats held in the Thumbor servers cache/result storage.

You can override the defaults and add extra formats via Strapi's plugin config file config/plugins.js. When defining a format you need to specify the key and its settings.

• key is the property the format will be stored on the original image upload object
• settings are the image manipulation settings supported by thumbor. These are passed to the thurl thumbor url generator. To see available options read the package documentation at https://www.npmjs.com/package/thurl.

Note: Plugin configuration will override defaults, so you should include the thumbnail and the small formats to show these formats in the Strapi admin.

override default sizes:

module.exports = ({env}) => ({
    thumborImageFormats: {
        // ... 
        thumbnail: {
            key: "thumbnail",
            settings: {width: 245, quality: 80},
        },
        formats: [{
            key: "small",
            settings: {width: 520},
        }]
    }
});

add extra formats:

module.exports = ({env}) => ({
    thumborImageFormats: {
        // ...
        thumbnail: {
            key: "thumbnail",
            width: 245,
        },
        formats: [
            {
                key: "small",
                settings: { width: 520}
            },
            {
                key: "medium",
                settings: {width: 720}
            },
            {
                key: "large",
                setting: {width: 1080}
            },
            {
                key: "grayscale",
                setting: {width: 1080, grayscale: ''}
            },
            {
                key: "blured",
                setting: {width: 1080, blur: [25,50]}
            },
        ]
    }
});

Notes

Thanks to nicolashmln for the idea for this plugin based on the plugin strapi-plugin-responsive-image.