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

Overview / Resources
Why use imgix instead of gatsby-transform-sharp?
Get started
Usage
API
Miscellaneous
Upgrade Guides
- Upgrading from v1.x to v2
- Upgrading from @imgix/gatsby-transform-url
Contributors
License

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:

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.
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.
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!).
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.
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',
  URLPrefix: 'https:',
},

gatsby-source-datocms

{
  nodeType: "DatoCmsAsset",
  rawURLKey: 'entityPayload.attributes.url',
  fieldName: "imgixImage",
},

gatsby-source-drupal

// Drupal
{
  nodeType: 'File',
  rawURLKey: (node) => node.url,
  fieldName: 'imgixImage',
},

Manual config (if your node type doesn't exist above)

{
  // This is the GraphQL node type that you want to modify. There's
  // more info on how to find this below.
  nodeType: '',

  // This is used to pull the raw image URL from the node you want to
  // transform. The value here should be the path in the node that
  // contains the image URL to be transformed.
  // See more information below on how to set this.
  rawURLKey: 'imageUrlKey',

  // This is the name of imgix field that will be added to the type.
  fieldName: 'imgixImage',
},

The rawURLKey value needs to be the path to the raw image URL in the node data that should be transformed.

The steps to setting this value correctly is:

Set the option to:
```
rawURLKey: '';
```
Inspect the logged output. The plugin will try to find a suitable image url in the node's data for you, and if it successfully finds one, it will output the code to replace the function with in the corresponding error message.

For example, for ContentfulAsset, it will display the following error message:
```
Error when resolving URL value for node type Post. This probably means that
the rawURLKey function in gatsby-config.js is incorrectly set. Please read this
project's README for detailed instructions on how to set this correctly.

Potential images were found at these paths:
  - imageURL
    Set following configuration options:
      rawURLKey: 'imageURL'
      URLPrefix: 'https:'
```
As we can see, the correct value for the options are
```
rawURLKey: 'imageURL',
URLPrefix: 'https:'
```
If no value was suggested, you will need to inspect the logged output to find a suitable image URL that corresponds to the image you want to transform. For example, if we're searching ContentfulAsset's data, we see the following output in the console:
```
{
  // ...
  file: {
    url: '//images.ctfassets.net/../.jpg',
    details: { size: 7316629, image: [Object] },
    fileName: 'image.jpg',
    contentType: 'image/jpeg'
  },
  // ...
}
```
Therefore, we need to set the option to file.url, to return the url at node.file.url. NB: the value for rawURLKey is passed to lodash.get, so array indices, etc can also be used if necessary.
Set the option to the correct value, making sure that the URL includes an http or https. For this example, since the image URL didn't have a https, we have to add https to the URLPrefix option:
```
rawURLKey: 'file.url`,
URLPrefix: 'https:'
```

Finding a node's type

The easiest way to find a node's type is to copy the query to the GraphiQL explorer (can be found at localhost:8000/__graphql). Then, while holding Cmd or Ctrl, hover over the node that you are trying to find the type for.

In the screenshot below, we have hovered over the heroImage field, and we can see the type is ContentfulAsset. This is the value we can set in the plugin's config.

It's also possible to add __typeName to the GraphQL query to find the node type. This is useful if you are unable to use the GraphiQL explorer. Here we can see again that the node type is ContentfulAsset

Default imgix parameters

Setting auto: ['format', 'compress'] is highly recommended. This will re-format the image to the format that is best optimized for your browser, such as WebP. It will also reduce unnecessary wasted file size, such as transparency on a non-transparent image. More information about the auto parameter can be found here.

GatsbyImage support

This plugin now supports the latest GatsbyImage component, which delivers better performance and Lighthouse scores, while improving the developer experience.

To use this plugin with GatsbyImage, the usage is quite similar to the normal usage with gatsby-plugin-image. This plugin exposes a gatsbyImageData GraphQL field which is very similar to the native field.

Example:

import gql from 'graphql-tag';
import Img from 'gatsby-image';
import { GatsbyImage } from 'gatsby-plugin-image';

export default ({ data }) => {
  return (
    <GatsbyImage
      image={data.allContentfulAsset.edges[0].node.imgixImage.gatsbyImageData}
    />
  );
};

export const query = gql`
  {
    allContentfulAsset {
      edges {
        node {
          imgixImage {
            gatsbyImageData(width: 400, imgixParams: {})
          }
        }
      }
    }
  }
`;

Shared field params

The layout, width, height, aspectRatio, outputPixelDensities, breakpoints, sizes, and backgroundColor parameters are identical to the parameters offered by the native gatsbyImageData field, and the documentation for those fields can be found in the Gatsby documentation. The other added parameters are specific to imgix and they are documented in the GraphQL type definitions, which can be explored in GraphiQL (usually at http://localhost:8000/__graphiql)

Fluid Images

The following code will render a fluid image with gatsby-image. This code should already be familiar to you if you've used gatsby-image in the past.

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

export default ({ data }) => {
  return (
    <Img
      fluid={{
        ...data.allContentfulAsset.edges[0].node.imgixImage.fluid,
        sizes: '100vw',
      }}
    />
  );
};

export const query = gql`
  {
    allContentfulAsset {
      edges {
        node {
          imgixImage {
            fluid(imgixParams: {
              // pass any imgix parameters you want to here
            }) {
              ...GatsbyImgixFluid
            }
          }
        }
      }
    }
  }
`;

A full list of imgix parameters can be found here.

Although sizes is optional, it is highly recommended. It has a default of (max-width: 8192px) 100vw, 8192px, which means that it is most likely loading an image too large for your users. Some examples of what you can set sizes as are:

500px - the image is a fixed width. In this case, you should use fixed mode, described in the next section.
(min-width: 1140px) 1140px, 100vw - under 1140px, the image is as wide as the viewport. Above 1140px, it is fixed to 1140px.

Fixed Images

The following code will render a fixed image with gatsby-image. This code should already be familiar to you if you've used gatsby-image in the past.

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

export default ({ data }) => {
  return <Img fixed={data.allContentfulAsset.edges[0].node.imgixImage.fixed} />;
};

export const query = gql`
  {
    allContentfulAsset {
      edges {
        node {
          imgixImage {
            fixed(
              width: 960 # Width (in px) is required
              imgixParams: {}
            ) {
              ...GatsbyImgixFixed
            }
          }
        }
      }
    }
  }
`;

A full list of imgix parameters can be found here.

Generating imgix URLs

If you would rather not use gatsby-image and would instead prefer just a plain imgix URL, you can use the url field to generate one. For instance, you could generate a URL and use it for the background image of an element:

import gql from 'graphql-tag';

export default ({ data }) => {
  return (
    <div
      style={{
        backgroundImage: `url(${data.allContentfulAsset.edges[0].node.imgixImage.url})`,
        backgroundSize: 'contain',
        width: '100vw',
        height: 'calc(100vh - 64px)',
      }}
    >
      <h1>Blog Title</h1>
    </div>
  );
};

export const query = gql`
  {
    allContentfulAsset {
      edges {
        node {
          imgixImage {
            url(imgixParams: { w: 1200, h: 800 })
          }
        }
      }
    }
  }
`;

GraphQL `imgixImage` API

This feature can be best thought about as a replacement for gatsby-image-sharp for images that are statically defined at build time. This allows imgix URLs to be used with gatsby-image through the Gatsby GraphQL API. This feature transforms imgix URLs into a format that is compatible with gatsby-image. This can generate either fluid or fixed images. With this feature you can either display images that already exist on imgix, or proxy other images through imgix.

This feature supports many of the existing gatsby-image GraphQL that you know and love, and also supports most of the features of gatsby-image, such as blur-up and lazy loading. It also brings all of the great features of imgix, including the extensive image transformations and optimisations, as well as the excellent imgix CDN.

Configuration

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

module.exports = {
  //...
  plugins: [
    // your other plugins here
    {
      resolve: `@imgix/gatsby`,
      options: {
        domain: '<your imgix domain, e.g. acme.imgix.net>',
        defaultImgixParams: { auto: ['compress', 'format'] },
      },
    },
  ],
};

Setting { auto: ['compress', 'format'] } is highly recommended. This will re-format the image to the format that is best optimized for your browser, such as WebP. It will also reduce unnecessary wasted file size, such as transparency on a non-transparent image. More information about the auto parameter can be found here.

GatsbyImage support

This plugin now supports the latest GatsbyImage component, which delivers better performance and Lighthouse scores, while improving the developer experience.

To use this plugin with GatsbyImage, the usage is quite similar to the normal usage with gatsby-plugin-image. This plugin exposes a gatsbyImageData GraphQL field which is very similar to the native field.

Example:

import gql from 'graphql-tag';
import Img from 'gatsby-image';
import { GatsbyImage } from 'gatsby-plugin-image';

export default ({ data }) => {
  return <GatsbyImage image={data.imgixImage.gatsbyImageData} />;
};

export const query = gql`
  {
    imgixImage(url: "https://assets.imgix.net/amsterdam.jpg") {
      gatsbyImageData(width: 400, imgixParams: {})
    }
  }
`;

Shared field params

The layout, width, height, aspectRatio, outputPixelDensities, breakpoints, sizes, and backgroundColor parameters are identical to the parameters offered by the native gatsbyImageData field, and the documentation for those fields can be found in the Gatsby documentation. The other added parameters are specific to imgix and they are documented in the GraphQL type definitions, which can be explored in GraphiQL (usually at http://localhost:8000/__graphiql)

Fluid Images

The following code will render a fluid image with gatsby-image. This code should already be familiar to you if you've used gatsby-image in the past.

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

export default ({ data }) => {
  return <Img fluid={{ ...data.imgixImage.fluid, sizes: '100vw' }} />;
};

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

A full list of imgix parameters can be found here.

Although sizes is optional, it is highly recommended. It has a default of (max-width: 8192px) 100vw, 8192px, which means that it is most likely loading an image too large for your users. Some examples of what you can set sizes as are:

500px - the image is a fixed width. In this case, you should use fixed mode, described in the next section.
(min-width: 1140px) 1140px, 100vw - under 1140px, the image is as wide as the viewport. Above 1140px, it is fixed to 1140px.

Fixed Images

The following code will render a fixed image with gatsby-image. This code should already be familiar to you if you've used gatsby-image in the past.

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

export default ({ data }) => {
  return <Img fixed={data.imgixImage.fixed} />;
};

export const query = gql`
  {
    imgixImage(url: "/image.jpg") {
      fixed(
        width: 960 # Width (in px) is required
        imgixParams: {}
      ) {
        ...GatsbyImgixFixed
      }
    }
  }
`;

A full list of imgix parameters can be found here.

Generating imgix URLs

If you would rather not use gatsby-image and would instead prefer just a plain imgix URL, you can use the url field to generate one. For instance, you could generate a URL and use it for the background image of an element:

import gql from 'graphql-tag';

export default ({ data }) => {
  return (
    <div
      style={{
        backgroundImage: `url(${data.imgixImage.url})`,
        backgroundSize: 'contain',
        width: '100vw',
        height: 'calc(100vh - 64px)',
      }}
    >
      <h1>Blog Title</h1>
    </div>
  );
};

export const query = gql`
  {
    imgixImage(url: "/image.jpg") {
      url(imgixParams: { w: 1200, h: 800 })
    }
  }
`;

Using a Web Proxy Source

If you would like to proxy images from another domain, you should set up a Web Proxy Source. After doing this, you can use this source with this plugin as follows:

Set the plugin config in gatsby-config.js to the following:

module.exports = {
  //...
  plugins: [
    // your other plugins here
    {
      resolve: `@imgix/gatsby-source-url`,
      options: {
        domain: '<your proxy source domain, e.g. my-proxy-source.imgix.net>',
        secureURLToken: '...', // <-- now required, your "Token" from your source page
        defaultImgixParams: ['auto', 'format'],
      },
    },
  ],
};

Pass a fully-qualified URL to the url parameter in the GraphQL API. For example, to render a fixed image, a page would look like this:

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

export default ({ data }) => {
  return <Img fixed={data.imgixImage.fixed} />;
};

export const query = gql`
  {
    imgixImage(url: "https://acme.com/my-image-to-proxy.jpg") {
      # Now this is a full URL
      fixed(
        width: 960 # Width (in px) is required
      ) {
        ...GatsbyImgixFixed
      }
    }
  }
`;

URL Transform Function

This features allows imgix urls to be used with gatsby-image or gatsby-plugin-image. imgix urls are transformed into a format that is compatible with gatsby-image. This can generate either fluid, fixed images, or for gatsby-plugin-image, full-width, constrained, or fixed images. With this feature you can either display images that already exist on imgix, or proxy other images through imgix. It is important to note that this feature can only display images that are already on imgix or an imgix-compatible URL. To display images that are not using imgix, you will have to use one of the GraphQL APIs above.

⚠️ This means that Web Proxy Sources are not supported with this API. To use Web Proxy Sources, either of the other two APIs must be used.

Unfortunately, due to limitations of Gatsby, this feature does not support blurred placeholders. To use placeholders please use one of the other use cases/parts of this library

Gatsby-plugin-image Component and Hook

This plugin supports the new frontend Gatsby-plugin-image component. To use the component with this plugin, use the following code

import { ImgixGatsbyImage } from '@imgix/gatsby';

export const MyPageComponent = () => {
  return (
    <ImgixGatsbyImage
      // Must be an imgix URL
      src="https://assets.imgix.net/amsterdam.jpg"
      // This can be used to set imgix params
      imgixParams={{ crop: 'faces' }}
      // These are passed through to the gatsby-plugin-image component
      layout="constrained"
      width={768}
      // Set either
      aspectRatio={16 / 9}
      // or
      sourceWidth={5000}
      sourceHeight={4000}

      // Any other props offered by the gatsby-plugin-image component are
      // supported and passed straight through to the component
    />
  );
};

If you would like more control over the data flow, you can also use the hook that this package exports - getGatsbyImageData - like so:

import { getGatsbyImageData } from '@imgix/gatsby';
import { GatsbyImage } from 'gatsby-plugin-image';

export const MyPageComponent = () => {
  return <GatsbyImage
    image={getGatsbyImageData({
      // Must be an imgix URL
      src: "https://assets.imgix.net/amsterdam.jpg"
      // This can be used to set imgix params
      imgixParams: { crop: 'faces' }

      // These are passed through to the gatsby-plugin-image component
      layout: "constrained"
      width: 768

      // Set either
      aspectRatio: 16 / 9
      // or
      sourceWidth: 5000
      sourceHeight: 4000
    })}
  >
}

Basic Fluid Image

The following code will render a fluid image with gatsby-image. This code should already be familiar to you if you've used gatsby-image in the past.

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

// Later, in a gatsby page/component.
<Img
  fluid={buildFluidImageData(
    'https://assets.imgix.net/examples/pione.jpg',
    {
      // imgix parameters
      ar: 1.61, // required
      auto: ['format', 'compress'], // recommended for all images
      // pass other imgix parameters here, as needed
    },
    {
      sizes: '50vw', // optional, but highly recommended
    },
  )}
/>;

ar is required, since gatsby-image requires this to generate placeholders. This ar will also crop the rendered photo from imgix to the same aspect ratio. If you don't know the aspect ratio of your image beforehand, it is virtually impossible to use gatsby-image in this format, so we either recommend using another of our plugins, or using an img directly.

Setting auto: ['format', 'compress'] is highly recommended. This will re-format the image to the format that is best optimized for your browser, such as WebP. It will also reduce unnecessary wasted file size, such as transparency on a non-transparent image. More information about the auto parameter can be found here.

A full list of imgix parameters can be found here.

Although sizes is optional, it is highly recommended. It has a default of 100vw, which means that it might be loading an image too large for your users. Some examples of what you can set sizes as are:

500px - the image is a fixed width. In this case, you should use fixed mode, described in the next section.
(min-width: 1140px) 1140px, 100vw - under 1140px, the image is as wide as the viewport. Above 1140px, it is fixed to 1140px.

A full example of a fluid image in a working Gatsby repo can be found on CodeSandbox.

Basic Fixed Image

The following code will render a fixed image with gatsby-image. This code should already be familiar to you if you've used gatsby-image in the past.

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

// Later, in a gatsby page/component.
<Img
  fixed={buildFixedImageData('https://assets.imgix.net/examples/pione.jpg', {
    // imgix parameters
    w: 960, // required
    h: 540, // required
    auto: ['format', 'compress'], // recommended for all images
    // pass other imgix parameters here, as needed
  })}
/>;

The imgix parameters w and h are required, since these are used by gatsby-image to display a placeholder while the image is loading. Other imgix parameters can be added below the width and height.

Setting auto: ['format', 'compress'] is highly recommended. This will re-format the image to the format that is best optimized for your browser, such as WebP. It will also reduce unnecessary wasted file size, such as transparency on a non-transparent image. More information about the auto parameter can be found here.

A full list of imgix parameters can be found here.

An example of this mode in a full working Gatsby repo can be found on CodeSandbox.

API

GraphQL

The majority of the API for this library can be found by using the GraphiQL inspector (usually at https://localhost:8000/__graphql).

GraphQL Fragments

This library also provides some GraphQL fragments, such as GatsbyImgixFluid, and GatsbyImgixFluid_noBase64. The values of these fragments can be found at fragments.js

Gatsby/Plugin Configuration

The plugin options that can be specified in gatsby-config.js are:

Name	Type	Description
`domain`	`String`	The imgix domain to use for the image URLs. Usually in the format `.imgix.net`
`defaultImgixParams`	`Object`	Imgix parameters to use by default for every image. Recommended to set to `{ auto: ['compress', 'format'] }`.
`disableIxlibParam`	`Boolean`	Set to `true` to remove the `ixlib` param from every request. See this section for more information.
`secureURLToken`	`String`	When specified, this token will be used to sign images. Read more about securing images on the imgix Docs site.

URL Transform Function

`buildFixedImageData`

function buildFixedImageData(
  /**
   * An imgix url to transform, e.g. https://yourdomain.imgix.net/your-image.jpg
   */
  url: string,
  /**
   * A set of imgix parameters to apply to the image.
   * Parameters ending in 64 will be base64 encoded.
   * A full list of imgix parameters can be found here: https://docs.imgix.com/apis/url
   * Width (w) and height (h) are required.
   */
  imgixParams: { w: number; h: number } & IImgixParams,
  /**
   * Options that are not imgix parameters.
   * Optional.
   */
  options?: {
    /**
     * Disable the ixlib diagnostic param that is added to every url.
     */
    includeLibraryParam?: boolean;
  },
): {
  width: number;
  height: number;
  src: string;
  srcSet: string;
  srcWebp: string;
  srcSetWebp: string;
};

`buildFluidImageData`

export function buildFluidImageData(
  /**
   * An imgix url to transform, e.g. https://yourdomain.imgix.net/your-image.jpg
   */
  url: string,
  /**
   * A set of imgix parameters to apply to the image.
   * Parameters ending in 64 will be base64 encoded.
   * A full list of imgix parameters can be found here: https://docs.imgix.com/apis/url
   * The aspect ratio (ar) as a float is required.
   */
  imgixParams: {
    /**
     * The aspect ratio to set for the rendered image and the placeholder.
     * Format: float or string. For float, it can be calculated with ar = width/height. For a string, it should be in the format w:h.
     */
    ar: number | string;
  } & IImgixParams,
  /**
   * Options that are not imgix parameters.
   * Optional.
   */
  options?: {
    /**
     * Disable the ixlib diagnostic param that is added to every url.
     */
    includeLibraryParam?: boolean;
    /**
     * The sizes attribute to set on the underlying image.
     */
    sizes?: string;
  },
): {
  aspectRatio: number;
  src: string;
  srcSet: string;
  srcWebp: string;
  srcSetWebp: string;
  sizes: string;
};

Third-party integration helpers (e.g. for Gatsby source plugins)

This section is for third-party plugin developers of Gatsby plugins and sources that would like to expose the functionality of this library inside their own plugins natively. For example, the Prismic Gatsby plugin uses these APIs to expose fixed, fluid, url, and gatsbyImageData fields on its images that it exposes in its GraphQL API.

createImgixGatsbyTypes

This is the main function that should be used to reuse functionality from this library.

API

Parameter	Type	Required	Description
imgixClientOptions	`Object`		Any extra configuration to pass to new ImgixClient from @imgix/js-core (see here for more information).
resolveUrl	`(source) => string \| undefined`	✔	A callback to resolve the image URL from the source data provided to the resolver. The source data is provided by the resolver of the type you are adding the image fields too.
resolveWidth	`(source) => number \| undefined`		This callback can be used to provide the source (uncropped) width of the target image from the source data, if known. The data passed to this callback is the same as is passed to `resolveUrl`. If this callback is not provided, a network request will be made at build time to resolve this information.
resolveHeight	`(source) => number \| undefined`		This callback can be used to provide the source (uncropped) height of the target image from the source data, if known. The data passed to this callback is the same as is passed to `resolveUrl`. If this callback is not provided, a network request will be made at build time to resolve this information.
allowListFields	`Array`		This can be used to restrict the types and fields generated to avoid creating extra unnecessary types. Possible values: url, fixed, fluid, gatsbyImageData.
defaultParams	`Object`		Default imgix parameters to apply for these images.
namespace	`String`		Prepends the types generated by this library with the supplied namespace to avoid name collisions. It is recommended to set this to something unique to your library so that if your developers import another Gatsby plugin that also this plugin that the names do not collide.
cache	`GatsbyCache`	✔	The Gatsby cache provided to Gatsby API hooks

Code example

// gatsby-node.js
const imgixGatsby = require('@imgix/gatsby/dist/pluginHelpers');

exports.createSchemaCustomization = async (gatsbyContext, options) => {
  const imgixTypes = imgixGatsby.createImgixGatsbyTypes({
    cache: gatsbyContext.cache,
    resolveUrl: (node) => node.imageURL,
    resolveWidth: (node) => node.imageSourceWidth,
    resolveHeight: (node) => node.imageSourceHeight,
    defaultParams: { auto: 'compress,format' },
    namespace: 'Imgix',
    imgixClientOptions: {
      // domain is required if urls are not already imgix urls. If a domain is provided here, and the image urls are not imgix urls, the the imgix source needs to be a web proxy source, and a secureURLToken token is required (see below).
      domain: 'my-imgix-domain.imgix.net',
      // secureURLToken is required if imgix source type is web proxy, or "secure URLs" is enabled in the imgix configuration dashboard
      secureURLToken: 'my-secure-url-token',
    },
  });

  const myNodeType = gatsbyContext.schema.buildObject({
    name: 'MyPluginNodeType',
    fields: {
      // Your other node fields, e.g. title, description, etc
      title: { type: 'String!' },

      // Add the fields returned from createImgixGatsbyTypes to your node as fields
      imageUrl: imgixTypes.fields.url,
      fluid: imgixTypes.fields.fluid,
      fixed: imgixTypes.fields.fixed,
      gatsbyImageData: imgixTypes.fields.gatsbyImageData,
    },
  });

  gatsbyContext.actions.createTypes([
    ...imgixTypes.types.map(gatsbyContext.schema.buildObjectType),
    ...imgixTypes.enumTypes.map(gatsbyContext.schema.buildEnumType),
    ...imgixTypes.inputTypes.map(gatsbyContext.schema.buildInputObjectType),
  ]);
  gatsbyContext.actions.createTypes(myNodeType);
};

Object builders

These low-level functions can be used to build data that can be passed straight to gatsby-image, or gatsby-plugin-image, if necessary. It is recommended to use createImgixGatsbyTypes instead of these functions.

`buildFluidObject`

import { buildFluidObject } from '@imgix/gatsby/dist/pluginHelpers';
import Img from 'gatsby-image';

const fluidData = buildFluidObject({
  // Image url, required. See note in section 'Note about url and imgixClientOptions' about what to do based on what kind of url this is
  url: 'https://domain.imgix.net/amsterdam.jpg',
  // Any extra configuration to pass to new ImgixClient from @imgix/js-core (see [here](https://github.com/imgix/js-core#configuration) for more information)
  imgixClientOptions: {
    domain: 'domain.imgix.net',
    secureURLToken: 'secure-token',
  },
  // Mimicking GraphQL field args
  args: {
    // Imgix params, required (at least {})
    imgixParams: {},
    // Imgix params for the placeholder image, required (at least {})
    placeholderImgixParams: {},
    // Max image width srcset to generate, required.
    maxWidth: 8192,
    // Max image height to generate, optional.
    maxHeight: 5000,
    // Custom src set breakpoints to set, optional.
    srcSetBreakpoints: [100, 200],
  },
  // The height in px of the original image, required
  sourceHeight: 3000,
  // The width in px of the original image, required
  sourceWidth: 4000,
  // Default params to set, required
  defaultParams: {},
  // Default placeholder params to set, required
  defaultPlaceholderParams: {},
});

// In component later...
<Img fluid={fluid} />;

`buildFixedObject`

import { buildFixedObject } from '@imgix/gatsby/dist/pluginHelpers';
import Img from 'gatsby-image';

const fixedData = buildFixedObject({
  // Image url, required. See note in section 'Note about url and imgixClientOptions' about what to do based on what kind of url this is
  url: 'https://domain.imgix.net/amsterdam.jpg',
  // Any extra configuration to pass to new ImgixClient from @imgix/js-core (see [here](https://github.com/imgix/js-core#configuration) for more information)
  imgixClientOptions: {
    domain: 'domain.imgix.net',
    secureURLToken: 'secure-token',
  },
  // Mimicking GraphQL field args
  args: {
    // Imgix params, required (at least {})
    imgixParams: {},
    // Imgix params for the placeholder image, required (at least {})
    placeholderImgixParams: {},
    // The width of the image in px for the 1x image, required.
    width: 100,
    // The height of the image in px for the 1x image, optional
    height: 200,
    // The imgix quality param to set, optional.
    quality: 50,
  },
  // The height in px of the original image, required
  sourceHeight: 3000,
  // The width in px of the original image, required
  sourceWidth: 4000,
  // Default params to set, required
  defaultParams: {},
  // Default placeholder params to set, required
  defaultPlaceholderParams: {},
});

// In component later...
<Img fixed={fixed} />;

`buildGatsbyImageDataObject`

import { buildGatsbyImageDataObject } from '@imgix/gatsby/dist/pluginHelpers';
import { GatsbyImage } from 'gatsby-plugin-image';

const gatsbyImageData = buildGatsbyImageDataObject({
  // Image url, required. See note in section 'Note about url and imgixClientOptions' about what to do based on what kind of url this is
  url: 'https://domain.imgix.net/amsterdam.jpg',
  // Any extra configuration to pass to new ImgixClient from @imgix/js-core (see [here](https://github.com/imgix/js-core#configuration) for more information)
  imgixClientOptions: {
    domain: 'domain.imgix.net',
    secureURLToken: 'secure-token',
  },
  // Mimicking GraphQL field args
  resolverArgs: {
    // The gatsby-plugin-image layout parameter
    layout: 'fullWidth',
    // Imgix params, optional
    imgixParams: {},
    // Imgix params for the placeholder image, optional
    placeholderImgixParams: {},
    // The width or max-width (depending on the layout setting) of the image in px, optional.
    width: 100,
    // The height or max-height (depending on the layout setting) of the image in px, optional.
    height: 200,
    // The aspect ratio of the srcsets to generate, optional
    aspectRatio: 2,
    // Custom srcset breakpoints to use, optional
    breakpoints: [100, 200],
    // Custom 'sizes' attribute to set, optional
    sizes: '100vw',
    // Custom srcset max width, optional
    srcSetMaxWidth: 8000,
    // Custom srcset min width, optional
    srcSetMinWidth: 100,
    // The factor used to scale the srcsets up, optional.
    // E.g. if srcsetMinWidth is 100, then the srcsets are generated as follows
    // while (width < maxWidth) nextSrcSet = prevSrcSet * (1 + widthTolerance)
    widthTolerance: 0.08,
  },
  // source width and of the uncropped image
  dimensions: { width: 5000, height: 3000 },
});

<GatsbyImage image={gatsbyImageData} />;

Note about url and imgixClientOptions

Depending on what kind of image URL url is set to in the above object helpers, domain and secureURLToken might have to be passed in imgixClientOptions.

If url is:

an imgix URL, domain and secureURLToken are likely not required. If domain is set, the source must be a Web Proxy Source. If "secure URLs" are enabled on the imgix source, or the source is a Web Proxy Source, secureURLToken is required.
a path (e.g. just /image.jpg), domain is required, and the domain should point to an imgix S3, GCP, Azure, or Web Folder source. secureURLToken is only required if "secure URLs" are enabled on the imgix source.
not an imgix URL, domain and secureURLToken are required, and domain should point to a Web Proxy imgix source.

Miscellaneous

What is the `ixlib` Param on Every Request?

For security and diagnostic purposes, we tag all requests with the language and version of the library used to generate the URL. To disable this, we provide two options.

For disabling the ixlib parameter across all requests, we provide disableIxlibParam as a plugin option for use in gatsby-config.js.

// gatsby-config.js
module.exports = {
  //...
  plugins: [
    // your other plugins here
    {
      resolve: `@imgix/gatsby`,
      options: {
        domain: '<domain.imgix.net>',
        disableIxlibParam: 'true', // this disables the ixlib parameter
        defaultImgixParams: { auto: ['compress', 'format'] },
      },
    },
  ],
};

For disabling ixlib on a case by case basis, we provide the includeLibraryParam parameter. When calling either of this library's two exported functions, in the third parameter set includeLibraryParam to false. For example, for buildFluidImageData:

<Img
  fluid={buildFixedImageData(
    'https://assets.imgix.net/examples/pione.jpg',
    {
      w: 960,
      h: 540,
    },
    {
      includeLibraryParam: false, // this disables the ixlib parameter
    },
  )}
/>

GraphQL Type Customization Warning

@imgix/gatsby customizes existing GraphQl types in order to expose our own types on those same fields. This allows for a more seamless integration with Gatsby. It also means that you might see a warning like this:

warn Plugin `@imgix/gatsby` has customized the GraphQL type `ShopifyCollectionImage`, which has already been defined by the plugin `gatsby-source-shopify`. This could potentially cause conflicts.

This warning can be safely ignored, ie this should not impact your build in any way.

This warning stems from the fact that type inference is "not allowed" in Gatsby plugins. In other words, Gatsby assumes that plugins are not modifying types that they do not own. Therefore it logs a warning whenever types are modified by a plugin that did not create them.

Gatsby does this in an effort to reduce the likelihood installing one plugin can break an entire build. If one plugin can change any plugin's type, it can break any plugin in the build. gatsby-imgix only modifies types that the user explicitly denotes as their image types. So we don't run the risk of overwriting or modifying types outside a source's explicitly denoted image types.

You can read more about this if you’re interested in this issue.

Multiple imgix Sources

You might find yourself with multiple imgix sources and wondering how you could use them at the same time with this plugin. There are a few possibilities for this, which will be outlined below.

Any number of sources can be used simultaneously with the URL transform API.

Example:

import { ImgixGatsbyImage } from '@imgix/gatsby';

export const MyPageComponent = () => (
  <div>
    <ImgixGatsbyImage src="https://first-source.imgix.net/image.jpg" />
    <ImgixGatsbyImage src="https://second-source.imgix.net/image.jpg" />
  </div>
);

The caveats with this approach is that you don't get the benefits of the GraphQL APIs (blur-up, etc), and that the sources must not be Web Proxy sources (for these you must use one of the GraphQL APIs).

Additionally, a source can be configured for one of the GraphQL APIs, and this source can be a Web Proxy source. Thus seemingly you could combine one of the GraphQL APIs and the URL transform API together to use multiple sources this way:

import gql from 'graphql-tag';
import Img from 'gatsby-image';
import { GatsbyImage } from 'gatsby-plugin-image';
import { ImgixGatsbyImage } from '@imgix/gatsby';

export default ({ data }) => (
  <div>
    <GatsbyImage image={data.imgixImage.gatsbyImageData} />;
    <ImgixGatsbyImage src="https://second-source.imgix.net/image.jpg" />
  </div>
);

export const query = gql`
  {
    imgixImage(url: "https://assets.imgix.net/amsterdam.jpg") {
      gatsbyImageData(width: 400, imgixParams: {})
    }
  }
`;

So, to summarise, it is possible to use multiple sources in this plugin. You have the option to use up to one source of any type with the GraphQL API, and then any number of non-Web Proxy sources with the URL transform API.

Upgrade Guides

Upgrading from v1.x to v2

Between v1 and v2, the method to retrieve the image url in the GraphQL from the raw data was changed. This was done to support Gatsby v4, as function configuration options are no longer possible in Gatsby v4. If you do not use the GraphQL transform API, then you do not have to change anything.

To upgrade from v1 to v2, the following configuration options need to be updated:

// gatsby-config.js
module.exports = {
  plugins: {
    // ...
    {
      resolve: `@imgix/gatsby`,
      options: {
        // ...
        fields: [
          {
            nodeType: "Post",
            fieldName: "imgixImage",

            // The follow option needs to be changed...
            getURL: node => `https:${node.banner.imageURL}`,

            // to this:
            rawURLKey: "banner.imageURL",
            URLPrefix: "https:",
          },
        ],
      },
    },
  }
}

Upgrading from `@imgix/gatsby-transform-url`

@imgix/gatsby-transform-url was deprecated in favor of combining these sub-projects into one single project, for simplicity.

The functionality of that library can be found, unchanged, under this new package. Specifically, all that needs to changed is the import statements, e.g. from

import { buildFluidImageData } from '@imgix/gatsby-transform-url';

to

import { buildFluidImageData } from '@imgix/gatsby';

Contributors

Contributions are a vital part of this library and imgix's commitment to open-source. We welcome all contributions which align with this project's goals. More information can be found in the contributing documentation.

imgix would like to make a special announcement about the prior work of Angelo Ashmore from Wall-to-Wall Studios on his gatsby plugin for imgix. The code and API from his plugin has made a significant contribution to the codebase and API for imgix's official plugins, and imgix is very grateful that he agreed to collaborate with us.

Thanks goes to these wonderful people (emoji key):

_{Frederick Fogerty}
💻 📖 🚧

_{Angelo Ashmore}
💻

_{Luis H. Ball Jr.}
📖

_{Sherwin Heydarbeygi}
📖

This project follows the all-contributors specification.

Files

README.md

Latest commit

History

README.md

File metadata and controls

Overview / Resources

Why use imgix instead of gatsby-transform-sharp?

Get started

Usage

What section should I read?

GraphQL transform API

Configuration

Adding a fields item correctly

gatsby-source-contentful

gatsby-source-datocms

gatsby-source-drupal

Manual config (if your node type doesn't exist above)

Finding a node's type

Default imgix parameters

GatsbyImage support

Shared field params

Fluid Images

Fixed Images

Generating imgix URLs

GraphQL imgixImage API

Configuration

GatsbyImage support

Shared field params

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

API

Code example

Object builders

buildFluidObject

buildFixedObject

buildGatsbyImageDataObject

Note about url and imgixClientOptions

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

Adding a `fields` item correctly

GraphQL `imgixImage` API

`buildFixedImageData`

`buildFluidImageData`

`buildFluidObject`

`buildFixedObject`

`buildGatsbyImageDataObject`

What is the `ixlib` Param on Every Request?

Upgrading from `@imgix/gatsby-transform-url`