@imgix/gatsby-source-url is a library to transform imgix urls to a format compatible with gatsby-image.
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:
- Set the plugin config in
gatsby-config.jsto 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
urlparameter 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:
| Name | Type | Required | 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. |
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.
