imgix

A Strapi Plugin to integrate imgix with your Strapi Media Library.

Table of Contents

1. Versions
2. Features
3. Requirements
4. Installation
5. Configuration
   • imgix configuration
   • Settings page configuration
   • File configuration file
   • Security Middleware Configuration
6. Rendering images
7. Contributing

Versions

• Strapi v5 - (current) v2.x
• Strapi v4 - v1.x

Features

Serve Strapi assets from an imgix Source

If you manage your assets using Strapi's built-in Media Library, this plugin allows you to rewrite the asset URLs so that they are served from an imgix Source.

Integration with Strapi Upload Providers

If your imgix Source is configured with a storage provider like Amazon S3, you can use this plugin to configure the Strapi Media Library to fetch assets directly from your imgix Source. You should also configure the corresponding Strapi Upload Provider.

Requirements

Complete installation requirements are exact same as for Strapi itself and can be found in the documentation under Installation Requirements.

Minimum environment requirements

• Node.js >=18.0.0 <=20.x.x
• NPM >=6.x.x

In our minimum support we're following official Node.js releases timelines.

Supported Strapi versions:

• Strapi v5.0.0 (recently tested)
• Strapi v5.x

Installation

From the Strapi Marketplace

As a verified Strapi plugin, we're available on the Strapi Marketplace as well as In-App Marketplace where you can follow the installation instructions.

From the command line

You can install this plugin from NPM within your Strapi project.

yarn add strapi-plugin-imgix@latest

Once installed, you must re-build your Strapi instance.

yarn build
yarn develop

Alternatively, you can run Strapi in the development mode with --watch-admin option:

yarn develop --watch-admin

The imgix plugin will appear in the Plugins section of Strapi sidebar after the app rebuilds.

You can now configure the plugin.

Configuration

To use the imgix plugin, you must first create an imgix account and Source if you haven't already.

Then you can configure your Strapi instance using the dedicated Settings page.

imgix configuration

1. Create an account
2. Setup source
3. (optional) Create token / API key - Required for non-webfolder source types. Ensure that the generated key has the following permission: Sources

Settings page configuration

You can access the configuration page via Strapi Settings -> Section: IMGIX Plugin -> Configuration.

You must specify following properties:

• Source - Webfolder or Other (S3, Azure, R2, etc)
• Media Library Source URL - Example: http://localhost:1337/uploads/
• imgix Source URL - Example: https://sdk-test.imgix.net

When using Other source types, you must fill our the Source ID and API Key fields. This enables the plugin to purge and add assets using the imgix Management API.

How Asset URL Paths Get Re-Written

Once you've configured the plugin it automatically rewrites the URLs of your assets to point to the imgix URL. For example, if you have an image at https://mydomain.com/uploads/amsterdam.jpg, the plugin will rewrite the URL to https://sdk-test.imgix.net/amsterdam.jpg. You must configure your imgix source to point into the resources path of your web folder, like /uploads.

!NOTE Default configuration for your plugin is fetched from config/plugins.{js,ts} or directly from the plugin itself. To customize the default state to revert to, see the file configuration section.

File configuration

If you do net yet have a config/plugins.{js,ts} or config/<env>/plugins.{js,ts} file, create it manually.

Otherwise, add the imgix config to the existing plugins configurations.

1// config/plugins.{js,ts}
2
3module.exports = ({ env }) => ({
4  //...
5  'imgix': {
6    enabled: true,
7    config: {
8        mediaLibrarySourceUrl: '<MEDIA SOURCE OF YOUR PROVIDER OR YOUR DOMAIN>', // Example: https://my-awss3-bucket-for-strapi.s3.eu-central-1.amazonaws.com/ or https://mydomain.com/uploads/
9        apiKey: '<YOUR IMGIX API KEY / TOKEN HERE>',
10        source: {
11            type: '<SOURCE TYPE>' // 'other' or 'webfolder'. Default: 'other'
12            id: '<SOURCE ID STRING>', // Example:
13            url: '<IMGIX SOURCE URL>', // Example: https://sdk-test.imgix.net
14        },
15    },
16  },
17  //...
18});

See Strapi plugin configuration documentation for more information.

Security Middleware Configuration

The default settings of the Strapi Security Middleware will not allow you to display uploaded images thumbnails directly in the Media Library interface. You will need to modify the contentSecurityPolicy settings by replacing strapi::security string with the object bellow instead.

1// config/middlewares.{js,ts}
2
3module.exports = [
4  // ...
5  {
6    name: "strapi::security",
7    config: {
8      contentSecurityPolicy: {
9        useDefaults: true,
10        directives: {
11          "connect-src": ["'self'", "https:"],
12          "img-src": [
13            "'self'",
14            "data:",
15            "blob:",
16            "market-assets.strapi.io",
17            "<IMGIX SOURCE URL>", // Example: https://sdk-test.imgix.net
18          ],
19          "media-src": [
20            "'self'",
21            "data:",
22            "blob:",
23            "market-assets.strapi.io",
24            "<IMGIX SOURCE URL>", // Example: https://sdk-test.imgix.net
25          ],
26          upgradeInsecureRequests: null,
27        },
28      },
29    },
30  },
31  // ...
32];

Properties

• mediaLibrarySourceUrl - url of your local / provider image source of Strapi Media Library. Example: http://localhost:1337/public/images/
• apiKey - imgix Management API Key (setup)
• source.id - your imgix source id as a 24-character string (setup)
• source.url - you imgix source url / subdomain. Example: https://sdk-test.imgix.net

Administration actions

Plugin provides bunch of administration actions you can perform.

• Restore configuration - you're forcing plugin to get configuration from the config/plugins.{js,ts} or config/<env>/plugins.{js,ts} file and overwrite current settings.
• Sync Media Library - Assets existing in Strapi Media Library are forced to work with the plugin. Their paths are overwritten based on current plugin configuration, like Media Library Source URL → Source URL / Subdomain.
• Desync Media Library - Assets existing in Strapi Media Library are forced work with your configured provider. Their paths are overwritten back based on current plugin configuration, like Source URL / Subdomain → Media Library Source URL.

Rendering images

Images provided by the Strapi Media Library with imgix Integration Plugin runing enables you to use the full set of imgix functionalities out of the box using a Render API query parameters or SDKs.

Rendering API

See the full documentation here

SDK

imgix support multiple different frontend libraries by ready to use SDKs, like:

• JavaScript
• React
• Vue
• and more.

To get the full list please check the dedicated Libraries directory.

Contributing

Development

Prerequisites

• yarn - installed globally
• yarnc - installed globally

1. Clone repository

   1git clone git@github.com:imgix/strapi-plugin-imgix.git

2. Run install & develop build command

   1// Install all dependencies
   2yarn install
   3
   4// Watch for file changes using `plugin-sdk` and follow the instructions provided by this official Strapi developer tool
   5yarn watch:link

3. Within the Strapi project, modify config/plugins.{js,ts} for imgix

1//...
2'imgix': {
3  enabled: true,
4  //...
5}
6//...

4. Run your Strapi instance