Nutella with Pepperoni and Mushrooms

    gatsby-plugin-remote-images

    3.4.0 • Public • Published

    💾 gatsby-plugin-remote-images

    Download images from any string field on another node so that those images can be queried with gatsby-image.

    Usage

    Install

    First, install the plugin.

    npm install --save gatsby-plugin-remote-images

    Second, set up the gatsby-config.js with the plugin. The most common config would be this:

    module.exports = {
      plugins: [
        {
          resolve: `gatsby-plugin-remote-images`,
          options: {
            nodeType: 'MyNodes',
            imagePath: 'path.to.image',
          },
        },
      ],
    };

    Options

    Option Name Description Required Default
    nodeType The node type that has the images you want to grab. This is generally the title-cased version of the word after the 'all' in GraphQL ie. allMyImages type is MyImages null
    imagePath For simple object traversal, this is the string path to the image you want to use, relative to the node. This uses lodash .get, see docs for accepted formats here. For traversing objects with arrays at given depths, see how to handle arrays along the path below. null
    name Name you want to give new image field on the node. Defaults to localImage. localImage
    auth Adds htaccess authentication to the download request if passed in. {}
    ext Sets the file extension. Useful for APIs that separate the image file path from its extension. Or for changing the extension. Defaults to existing file extension. null
    prepareUrl Allows modification of the URL per image if needed. Expects a function taking the original URL as a parameter and returning the desired URL. null
    type Tell the plugin that the leaf node is an array of images instead of one single string. Only option here is array. For example usage, see here. object
    silent Set to true to silence image load errors in the console. boolean

    Example Config with Optional Options

    However, you may need more optional config, which is documented here.

    module.exports = {
      plugins: [
        {
          resolve: `gatsby-plugin-remote-images`,
          options: {
            nodeType: 'MyNodes',
            imagePath: 'path.to.image',
            // ** ALL OPTIONAL BELOW HERE: **
            name: 'theNewImageField',
            auth: { htaccess_user: `USER`, htaccess_pass: `PASSWORD` },
            ext: '.jpg',
            prepareUrl: url => (url.startsWith('//') ? `https:${url}` : url),
          },
        },
      ],
    };

    Why?

    Why do you need this plugin? The fantastic gatsby-image tool only works on relative paths to locally stored images. This lets you use it on images from an API with an absolute path. For example, look at these two response from one GraphQL query:

    Query

    allMyNodes {
        edges {
          node {
            id
            imageUrl
          }
        }
      }

    Absolute imageUrl NOT available to gatsby-image

    allMyNodes: [
      {
        node: {
          id: 123,
          imageUrl: 'http://remoteimage.com/url.jpg',
        },
      },
    ];

    Relative imageUrl IS available to gatsby-image

    allMyNodes: [
      {
        node: {
          id: 123,
          imageUrl: 'localImages/url.jpg',
        },
      },
    ];

    If you don't control the API that you are hitting (many third party APIs return a field with a string to an absolute path for an image), this means those image aren't run through gatsby-image and you lose all of the benefits.

    To get the images and make them available for the above example, follow the install instructions and your config should look like this:

    module.exports = {
      plugins: [
        {
          resolve: `gatsby-plugin-remote-images`,
          options: {
            nodeType: 'MyNodes',
            imagePath: 'imageUrl',
            // OPTIONAL: Name you want to give new image field on the node.
            // Defaults to 'localImage'.
            name: 'allItemImages',
          },
        },
      ],
    };

    Now, if we query allMyNodes we can query as we would any gatsby-image node:

    allMyNodes {
      edges {
        node {
          localImage {
            childImageSharp {
              fluid(maxWidth: 400, maxHeight: 250) {
                ...GatsbyImageSharpFluid
              }
            }
          }
        }
      }
    }

    Note: Many Gatsby source plugins already do this work for you under the hood. So if you are working with a common CMS's Gatsby plugin, odds are that you don't need this!

    Common Issues

    gatsby-source-graphql

    Due to the way gatsby-source-graphql creates nodes, it is currently impossible for any transformer type plugin to traverse the data from that plugin. Please read this issue for explanation. As soon as that as fixed in gatsby-source-graphql, this plugin will be tested to make sure it works with it as well.

    Traversing objects with arrays

    Since some GraphQL APIs will send back objects with nested arrays where your target data lives, gatsby-plugin-remote-images also supports traversing objects that have arrays at arbitrary depths. To opt in to this feature, add an array literal, [], to the end of the node you want to indicate is an array.

    Given an object structure like this:

    allMyNodes {
      nodes: [
        {
          imageUrl: 'https://...'
        },
        ...
      ]
    }

    To get the images and make them available for the above example, your config should look like this:

    module.exports = {
      plugins: [
        {
          resolve: `gatsby-plugin-remote-images`,
          options: {
            nodeType: 'MyNodes',
            imagePath: 'nodes[].imageUrl',
          },
        },
      ],
    };

    Now, if we query allMyNodes we can query as we would any gatsby-image node:

    allMyNodes {
      nodes {
        localImage {
          childImageSharp {
            fluid(maxWidth: 400, maxHeight: 250) {
              ...GatsbyImageSharpFluid
            }
          }
        }
      }
    }

    Note: While lodash .get doesn't natively support this syntax, it is still used to traverse the object structure, so the documentation for .get still applies in full.

    Handling an Array of Image URLs

    In case your API offers an image path to an array of images, instead of just one, there is a way to handle that with the plugin. For instances where there is an array somewhere along the path to the images, see above.

    For example, you API returns:

    // MyNode
    {
      date: '1-1-2010',
      category: 'cats'
      // Note that here there are multiple images at the *leaf* node where the images are found.
      images: [
        'https://.../image1.png',
        'https://.../image2.png'
      ]
    }

    To make your local image field an array of these images, adjust your config accordingly:

     {
       resolve: `gatsby-plugin-remote-images`,
       options: {
         nodeType: 'MyNodes',
         // Making this plural (optional).
         name: 'localImages',
         // Path to the leaf node.
         imagePath: 'images',
         // Set type to array.
         type: 'array'
       }
    }

    Now, if we query allMyNodes we can query as we would any gatsby-image node, but now localImage (or localImages as in the example above) we would get an array of Gatsby images, instead of just one.

    allMyNodes {
      nodes {
        localImages {
          childImageSharp {
            fluid(maxWidth: 400, maxHeight: 250) {
              ...GatsbyImageSharpFluid
            }
          }
        }
      }
    }

    Install

    npm i gatsby-plugin-remote-images

    DownloadsWeekly Downloads

    3,592

    Version

    3.4.0

    License

    MIT

    Unpacked Size

    19.6 kB

    Total Files

    3

    Last publish

    Collaborators

    • graysonhicks