Introducing Our Gatsby Plugin

header image

User feedback is incredibly important to us. We always aim to deliver the product enhancements that our customers ask for. Recently, many of our customers have requested support for the fast-growing framework Gatsby.

You asked, and we listened. We’re excited to announce an imgix plugin for Gatsby. This post dives into why we developed a Gatsby plugin and shares three top use cases for our plugin.

Why Gatsby

Gatsby is an open-source static website generator based on the React framework that enables users to create performant, scalable websites (static and dynamic). It has become an increasingly popular choice for e-commerce sites, news sites, blogs, and more.

Despite being a newer framework that is relatively early in its development, Gatsby bills themselves as providing:

  • A great developer experience
  • Best-in-class performance
  • Adherence to the latest web standards
  • Out-of-the-box Progressive Web App support
  • Built-in accessibility
  • Active developer ecosystem that provides plugins

In addition, Gatsby Cloud’s custom-built architecture simplifies the process of deployment to production.

Our Plugin

Broadly speaking, our Gatsby plugin works as a replacement for gatsby-plugin-sharp, and processes your images through imgix, rather than on your machine. This allows you to speed up your development time since image processing will no longer slow down your builds. Furthermore, our plugin can improve the responsiveness of your images, since we create many more different image variants than gatsby-plugin-sharp does. Finally, you gain access to our full suite of transformations and optimizations.

Our plugin serves three main use cases: images provided by a Gatsby source, images that are statically defined at build time, and images that are set dynamically. We’ll discuss each in greater detail below.

1. Images Provided by a Gatsby Source

The most popular use case involves data loaded from a Gatsby source such as Contentful or Prismic, which provides the image that you want to transform. For example, imagine that the Gatsby source is loading product information that contains a product image. This product image is normally stored at some URL on the web, e.g. provided by your CMS.

Our plugin will take this URL and proxy it through imgix, allowing you to transform and optimize that image. For this use case you’ll need a Web Proxy Source.

You can then use this new image with the Gatsby-image component, which has features such as lazy loading, blur up or placeholder images, fluid/fixed rendering, and plenty of performance optimizations. Alternatively, you can use it with a bare <img> component, or however else you prefer.

Below is an example of code showing a “fluid image”. Notice that the usage is very similar to how a developer would normally use gatsby-image.

import gql from 'graphql-tag';
import Img from 'gatsby-image';

// Component
export default ({ data }) => <Img fluid={data.post.imgixImage.fluid} />;

// Query
export const query = gql`
  {
    post(id: "id-123") {
      imgixImage {
        fluid(imgixParams: {
          // pass any imgix parameters you want to here
        }) {
          ...GatsbyImgixFluid // fragment provided by our plugin
        }
      }
    }
  }
`;

2. Statically Defined Images

This use case covers when the URL for the image is statically defined. Consider a website's logo or banner image, which is known and defined statically in the code.

This use case can work with any type of imgix Source, not just Web Proxy Sources. These images can be used in a similar way to images provided by a Gatsby Source, with all of the same benefits.

Below is an example of code showing a “fluid image” for this use case.

import gql from 'graphql-tag';
import Img from 'gatsby-image';

// Component
export default ({ data }) => <Img fluid={data.imgixImage.fluid} />;

// Query
export const query = gql`
  {
    imgixImage(url: "/image.jpg") {
      fluid(imgixParams: {
        // pass any imgix parameters you want to here
      }) {
        ...GatsbyImgixFluid
      }
    }
  }
`;

3. Dynamically Set Images

The third use case is for images that are loaded dynamically, such as an infinitely scrolling gallery. Since these images load after the page has loaded, we can’t use the same solution as we did above for statically defined images.

For this use case, the images can come from anywhere and use any type of imgix Source. However, the images cannot use some features such as placeholders or blur-up, as those are only available for images that load when the page loads.

Below is an example of code showing a “fluid image”.

import Img from 'gatsby-image';
import { buildFluidImageData } from '@imgix/gatsby';

// Component
export default () => (
  <Img
    fluid={buildFluidImageData(
      'https://assets.imgix.net/examples/pione.jpg',
      {
        // imgix parameters
        ar: 1.61, // required for placeholder behaviour
      },
      {
        sizes: '50vw', // optional, but highly recommended
      },
    )}
  />
);

Next Up

As with all of our libraries and plugins, we will continue updating this plugin. For starters, we are currently working on gatsby-plugin-image support, so stay tuned for that.

You can track updates and also vote on new features over at our GitHub repo, where you can also find install instructions, usage guides, and API docs.

Join Us at Gatsby Conf

We'll be hosting a workshop at next week’s virtual Gatsby Conf (March 2-3). Join us on March 3 at 11 am PST to learn about how our Gatsby plugin can help decrease build times and increase responsiveness. Register for your free conference pass here.

Stay up to date with our blog for the latest imgix news, features, and posts.