@imgix/gatsby-source-url is a library to transform imgix urls to a format compatible with gatsby-image.

• About This Library
• Get Started
  • Configuration
• Usage
  • Fluid Images
  • Fixed Images
  • Using a Web Proxy Source
• API
  • GraphQL
    • GraphQL Fragments
  • Gatsby/Plugin Configuration
• What is the ixlib Param on Every Request?
• Contributors

About This Library

This library can be best thought about as a part-replacement for gatsby-image-sharp, and allows imgix urls to be used with gatsby-image through the Gatsby GraphQL API. This library transforms imgix urls into a format that is compatible with gatsby-image. This can generate either fluid or fixed images. With this library you can either display images that already exist on imgix, or proxy other images through imgix.

This library 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.

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-source-url
• Yarn: yarn add @imgix/gatsby-source-url

Configuration

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

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

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.

Usage

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
      }) {
        ...GatsbySourceImgixFluid
      }
    }
  }
`;

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: {}
      ) {
        ...GatsbySourceImgixFixed
      }
    }
  }
`;

A full list of imgix parameters can be found here.

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:

1. 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'],
      },
    },
  ],
};

2. 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
      ) {
        ...GatsbySourceImgixFixed
      }
    }
  }
`;

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 GatsbySourceImgixFluid, and GatsbySourceImgixFluid_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:

What is the ixlib Param on Every Request?

For security and diagnostic purposes, we tag all requests with the language and version of library used to generate the URL.

To disable this, set disableIxlibParam to true in the plugin configuration options.

// gatsby-config.js
module.exports = {
  //...
  plugins: [
    // your other plugins here
    {
      resolve: `@imgix/gatsby-source-url`,
      options: {
        domain: '<your imgix domain, e.g. acme.imgix.net>',
        disableIxlibParam: true, // <-- set this to true
      },
    },
  ],
};

Contributors

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.