Gatsby

<!-- ix-docs-ignore -->

@imgix/gatsby is a multi-faceted plugin to help the developer use imgix with Gatsby.

<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->

<!-- ALL-CONTRIBUTORS-BADGE:END -->

---

<!-- /ix-docs-ignore --> <!-- NB: Run `npx markdown-toc README.md --maxdepth 4 | sed -e 's/[[:space:]]\{2\}/ /g' | pbcopy` to generate TOC :) --> <!-- prettier-ignore-start -->

• Overview / Resources
• Why use imgix instead of gatsby-transform-sharp?
• Get started
• Usage
  • What section should I read?
  • GraphQL transform API
    • Configuration
    • GatsbyImage support
    • Fluid Images
    • Fixed Images
    • Generating imgix URLs
  • GraphQL imgixImage API
    • Configuration
    • GatsbyImage support
    • Fluid Images
    • Fixed Images
    • Generating imgix URLs
    • Using a Web Proxy Source
  • URL Transform Function
    • Gatsby-plugin-image Component and Hook
    • Basic Fluid Image
    • Basic Fixed Image
• API
  • GraphQL
    • GraphQL Fragments
  • Gatsby/Plugin Configuration
  • URL Transform Function
    • buildFixedImageData
    • buildFluidImageData
  • Third-party integration helpers (e.g. for Gatsby source plugins)
    • createImgixGatsbyTypes
    • Object builders
• Miscellaneous
  • What is the ixlib Param on Every Request?
  • GraphQL Type Customization Warning
  • Multiple imgix Sources
• Upgrade Guides
  • Upgrading from v1.x to v2
  • Upgrading from @imgix/gatsby-transform-url
• Contributors
• License

<!-- prettier-ignore-end -->

Overview / Resources

Before you get started with this library, it's highly recommended that you read Eric Portis' seminal article on srcset and sizes. This article explains the history of responsive images in responsive design, why they're necessary, and how all these technologies work together to save bandwidth and provide a better experience for users. The primary goal of this library is to make these tools easier for developers to implement, so having an understanding of how they work will significantly improve your experience with this library.

Below are some other articles that help explain responsive imagery, and how it can work alongside imgix:

Why use imgix instead of gatsby-transform-sharp?

Integrating imgix with Gatsby provides a few key advantages over the core image experience in Gatsby:

1. Far-reduced build time and better developer experience. Since we offload the image rendering to our cloud, we free up your machine from doing complex image transformations, meaning your builds are as snappy as they can be.
2. Access to imgix's suite of transformations and optimizations. imgix has a larger variety of image transformations than are possible with the built in Gatsby system. Furthermore, we are continuously improving our image optimization to push the boundaries of image performance.
3. Better image responsiveness on the page. As we are able to create far more derivative images at different resolutions due to our cloud rendering stack, we can offer an image closer to the source resolution of your users' browsers, meaning faster load times and less bandwidth usage for your users (and you!).
4. Access to imgix's best-in-class CDN. imgix has invested significant time and effort into a world-leading CDN, which ensures images are delivered your website's customers as quick as possible.
5. Faster time-to-awesome. imgix offers a set of default optimizations which allow you to achieve outstanding image quality which still keeping image size small, and allows you to focus on other aspects of your website.

Get started

Firstly, this library requires an imgix account, so please follow this quick start guide if you don't have an account.

Then, install this library with the following commands, depending on your package manager.

• NPM: npm install @imgix/gatsby
• Yarn: yarn add @imgix/gatsby

Finally, check out the section in the usage guide below that most suits your needs.

Usage

What section should I read?

To find what part of this usage guide you should read, select the use case below that best matches your use case:

• I have images provided by a Gatsby source (e.g. Contentful, Prismic) 👉 graphql transform node API
• My images are statically defined at build time 👉 graphql imgixImage API
• My images are set dynamically (e.g. loaded from REST API on client) 👉 url transform function

GraphQL transform API

This feature can be best thought of as a replacement for gatsby-image-sharp, for images that are provided by Gatsby Source plugins, such as Contentful or Prismic. These plugins provide data that is accessed with the Gatsby GraphQL API, with images that are stored on the internet. This plugin can transform those images using imgix, and serve them to your customers.

Configuration

This source must be configured in your gatsby-config file as follows:

// Add to start of file
const { ImgixSourceType } = require('@imgix/gatsby');

module.exports = {
  //...
  plugins: [
    // your other plugins here
    {
      resolve: `@imgix/gatsby`,
      options: {
        // This is the domain of your imgix source, which can be created at
        // https://dashboard.imgix.com/.
        // Required for "Web Proxy" imgix sources.
        domain: 'example.imgix.net',

        // This is the source's secure token. Can be found under the "Security"
        // heading in your source's configuration page, and revealed by tapping
        // "Show Token". Required for web-proxy sources.
        secureURLToken: 'abcABC123',

        // This configures the plugin to work in proxy mode.
        // Can be AmazonS3, GoogleCloudStorage, MicrosoftAzure, or WebFolder.
        sourceType: ImgixSourceType.WebProxy,

        // These are some default imgix parameters to set for each image. It is
        // recommended to have at least this minimal configuration.
        defaultImgixParams: { auto: 'format,compress' },

        // This configures which nodes to modify.
        fields: [
          // Add an object to this array for each node type you want to modify. Follow the instructions below for this.
        ],
      },
    },
  ],
};

Adding a fields item correctly

It's necessary to add a configuration for each GraphQL node type you would like to modify. For example, if you have a page which queries both for blog posts, and also blog post categories, you will need to add items for each type separately.

The first step is to find the node type you would like to modify. To do this, look at the GraphQL query for the image you would like to modify. You need to find the node type for the node that image belongs to. For example, for the following query, the node type is ContentfulAsset, since that is the type of heroImage. This can be confirmed by copying the query into the GraphiQL editor and hovering over the node type. More detailed instructions on how to find the node types can be found in this section

query HomeQuery {
  allContentfulBlogPost {
    nodes {
      heroImage { # this is the node to modify
        fluid {...}
      }
    }
  }

}

Then, you need to configure a field for this node type. The quickest way to configure this is to see if the examples below include a configuration for the node that you would like to transform. If it exists, just copy and paste that into the list of fields, and you're done. Otherwise, skip to the section for manual setup.

gatsby-source-contentful

// ContentfulAsset
{
  nodeType: "ContentfulAsset",
  fieldName: "imgixImage",
  rawURLKey: 'file.url