If you’ve ever run into long build times on Gatsby sites due to images, this plugin is for you.

What is it?

gatsby-plugin-imgix is a new Gatsby plugin that connects your site’s images to an image transformation and CDN service named Imgix. Think of it as a mini Photoshop controlled through URL parameters.

Take this URL as an example:

https://walltowall.imgix.net/apples.jpg?sat=-100&w=600

sat=-100 removes all color saturation while w=600 sets the width to 600px.

Imgix provides a whole suite of parameters to transform images, all of which can be viewed at their API Reference.

Our new Gatsby plugin can take URLs from your content sources and map them to an Imgix-enabled version. If you are using a content management system such as WordPress, your image URLs can be proxied through Imgix. If your images are hosted locally, you can upload them to an online storage service like Amazon S3 and connect it to your Imgix account.

Because images can be transformed through URL parameters, you can define parameters specifically for different sections of your site. Need a duotone effect in your hero image? Imgix can do it. Need to crop an image and focus in on someone’s face? Imgix to the rescue.

This could all be done with existing plugins like gatsby-plugin-sharp where image processing is done on your computer or server at build time. Many Gatsby developers will eventually reach a point where image processing becomes the longest part of a website build. So long, in fact, that services like Netlify can actually time out. Offloading image processing to an external service like Imgix means we’re just manipulating strings at build time which is cheap and very fast.

Okay, cool. How do I use it?

First, you’ll need to sign up for an Imgix account. It’s not a free service, but pricing is reasonable at $3/1000 unique images + 8¢/GB of bandwidth. For each unique image, you can perform unlimited URL transformations.

Next, you’ll need to decide how to provide images to Imgix. Imgix can serve images from different sources, such as a Amazon S3 or your content management system. Configuration depends on where you store your images.

Local images

Imgix is “just” an image proxy and CDN and not a file manager. As such, Imgix does not allow uploading images to their servers directly through a UI. Instead, you’ll need to upload your images to a file storage service such as Amazon S3 and connect that service to your Imgix account.

Once connected, you can access your images through your unique Imgix subdomain.

Remote Images

If your images are hosted remotely from your site, such as through a content management system or file storage service, you can setup an Imgix Web Proxy. Instructions on doing so can be found at Imgix’s official documentation.

A web proxy source allows you to include your non-Imgix URL directly within the Imgix URL. A web proxy URL could look something like this:

https://walltowall.imgix.net/https%3A%2F%2Fdl.airtable.com%2F.attachments%2Fmy-image.jpg?w=2000&s=42021f7495fede06f329a8f3eb87a7dd

Here you can see an Airtable attachment served through Imgix with a width of 2000px. The s parameter at the end is a signature made with a unique secret associated with your Imgix account to ensure your website visitors cannot alter the URL.

Example configuration

Once your Imgix source is setup, add the Gatsby plugin to your site and configure your fields. Note that a web proxy source requires some additional configuration.

// gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-imgix',
      options: {
        // Imgix source domain. This is required.
        domain: 'example-domain.imgix.net',

        // Imgix source secure URL token. Providing this will automatically
        // secure all of your image URLs. This is required if your source type
        // is a Web Proxy.
        // See: https://docs.imgix.com/setup/securing-images
        //
        // Note that this is a private key and should be hidden behind an
        // environment variable.
        // See: https://www.gatsbyjs.org/docs/environment-variables/#server-side-nodejs
        secureUrlToken: process.env.IMGIX_SECURE_URL_TOKEN,

        // Imgix source type. If your source type is a Web Proxy, set this to
        // "webProxy". Otherwise, you may omit this field. URLs provided to the
        // plugin will automatically be converted to a Web Proxy-compatible URL
        // if set to "webProxy".
        sourceType: 'webProxy',

        // List of fields to copy into `fields` as Imgix images. You may list
        // as many fields as needed.
        fields: [
          {
            // The node type containing the image to copy.
            nodeType: 'MarkdownRemark',

            // Name of the new field to create. If you set this to
            // "featuredImage", a field at `fields.featuredImage` will be
            // created.
            fieldName: 'featuredImage',

            // Function to get the URL in the node. This function should return
            // the URL as a string. If your field contains an array of URLs,
            // change the `getUrl` option name to `getUrls`.
            getUrl: (node) => node.frontmatter.featured_image,
          },
        ],
      },
    },
  ],
}

With this example configuration, all MarkdownRemark nodes (i.e. Markdown files) will contain an Imgix URL at fields.featuredImage that can be manipulated through your GraphQL query.

const query = graphql`
  query AllMarkdownImages {
    allMarkdownRemark {
      nodes {
        id
        fields {
          featuredImage {
            # 50% quality and a heavy Gaussian blur
            url(imgixParams: { q: 50, blur: 200 })
          }
        }
      }
    }
  }
`

If you use gatsby-image, support is built-in and can be accessed using the fixed or fluid field along with a GraphQL fragment.

const query = graphql`
  query AllMarkdownImages {
    allMarkdownRemark {
      nodes {
        id
        fields {
          featuredImage {
            fluid(maxWidth: 1000, imgixParams: { q: 50, blur: 200 }) {
              ...GatsbyImgixFluid
            }
          }
        }
      }
    }
  }
`

More details on setting up and using the plugin are available at its README on GitHub.

What’s next?

This initial version of gatsby-plugin-imgix focuses on setting up a friendly API to hook into Imgix’s powerful image transformation service. It integrates with Gatsby’s system through its configuration and GraphQL queries, both with ample flexibility.

Our next focus is to allow programmatic access. This would allow plugin developers to use this plugin’s lower-level functions to provide Imgix functionality. Content management systems that already integrate with Imgix, for example, could use this to provide a robust API for Gatsby sites.

It’s actually already in use with gatsby-source-prismic. It still has a few bugs to work out, but integrating with gatsby-plugin-imgix provided a nice set of enhancements and allowed us to remove a healthy amount of code.

We’ve experienced significantly reduced build times with this plugin and hope it can do the same for you. Be sure to provide feedback or report bugs on GitHub.