{"id":13725486,"url":"https://github.com/graysonhicks/gatsby-plugin-remote-images","last_synced_at":"2025-04-04T20:16:19.680Z","repository":{"id":33691064,"uuid":"160727441","full_name":"graysonhicks/gatsby-plugin-remote-images","owner":"graysonhicks","description":":floppy_disk: A Gatsby.js plugin for downloading and linking remote images from another node's field for the benefits of gatsby-image.","archived":false,"fork":false,"pushed_at":"2024-05-06T12:52:49.000Z","size":4931,"stargazers_count":155,"open_issues_count":13,"forks_count":39,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T19:12:30.355Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/graysonhicks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-06T20:21:41.000Z","updated_at":"2024-06-14T19:56:06.000Z","dependencies_parsed_at":"2024-01-12T21:19:41.500Z","dependency_job_id":"7579d13a-7503-45ea-b5a9-5228aa1c8a62","html_url":"https://github.com/graysonhicks/gatsby-plugin-remote-images","commit_stats":{"total_commits":126,"total_committers":23,"mean_commits":5.478260869565218,"dds":0.5317460317460317,"last_synced_commit":"2cea9a6e545c0029749e810f7d56d03d190e7258"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graysonhicks%2Fgatsby-plugin-remote-images","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graysonhicks%2Fgatsby-plugin-remote-images/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graysonhicks%2Fgatsby-plugin-remote-images/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graysonhicks%2Fgatsby-plugin-remote-images/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/graysonhicks","download_url":"https://codeload.github.com/graysonhicks/gatsby-plugin-remote-images/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247242683,"owners_count":20907134,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T01:02:24.801Z","updated_at":"2025-04-04T20:16:19.656Z","avatar_url":"https://github.com/graysonhicks.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# 💾 gatsby-plugin-remote-images\n\nDownload images from any string field on another node so that those images can\nbe queried with `gatsby-plugin-image`.\n\n- [Usage](#usage)\n  - [Install](#install)\n  - [Options](#options) -\n    [Example Config with Optional Options](#example-config-with-optional-options)\n- [Why?](#why)\n- [Common Issues](#common-issues)\n\n  - [gatsby-source-graphql](#gatsby-source-graphql)\n  - [Traversing objects with arrays](#traversing-objects-with-arrays)\n  - [Handling an Array of Image URLs](#handling-an-array-of-image-urls)\n\n**Note:** This plugin support `gatsby-plugin-image` and drops support for\n`gatsby-image` in `3.0.0`.\n\n## Usage\n\n### Install\n\nFirst, install the plugin.\n\n`npm install --save gatsby-plugin-remote-images`\n\nSecond, set up the `gatsby-config.js` with the plugin. The most common config\nwould be this:\n\n```javascript\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-plugin-remote-images`,\n      options: {\n        nodeType: 'MyNodes',\n        imagePath: 'path.to.image',\n      },\n    },\n  ],\n};\n```\n\n### Options\n\n| Option Name       | Description                                                                                                                                                                                                                                                                                                                                      | Required | Default      |\n| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------ |\n| 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`       |\n| 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](https://lodash.com/docs/4.17.11#get). For traversing objects with arrays at given depths, see [how to handle arrays along the path below](#traversing-objects-with-arrays). | ✅       | `null`       |\n| name              | Name you want to give new image field on the node. Defaults to `localImage`.                                                                                                                                                                                                                                                                     | ❌       | `localImage` |\n| auth              | Adds htaccess authentication to the download request if passed in.                                                                                                                                                                                                                                                                               | ❌       | `{}`         |\n| 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`       |\n| 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`       |\n| 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](#handling-an-array-of-image-urls).                                                                                                                                                           | ❌       | `object`     |\n| silent            | Set to `true` to silence image load errors in the console.                                                                                                                                                                                                                                                                                       | ❌       | `boolean`    |\n| skipUndefinedUrls | This skips undefined `urls` and adds an easy way for the user to implement their own \"undefined\" values by returning undefined from the `prepareUrl()` function. See [here](https://github.com/graysonhicks/gatsby-plugin-remote-images/pull/134#issue-1568549719).                                                                              | ❌       | `boolean`    |\n\n#### Example Config with Optional Options\n\nHowever, you may need more optional config, which is documented here.\n\n```javascript\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-plugin-remote-images`,\n      options: {\n        nodeType: 'MyNodes',\n        imagePath: 'path.to.image',\n        // ** ALL OPTIONAL BELOW HERE: **\n        name: 'theNewImageField',\n        auth: { htaccess_user: `USER`, htaccess_pass: `PASSWORD` },\n        ext: '.jpg',\n        prepareUrl: url =\u003e (url.startsWith('//') ? `https:${url}` : url),\n      },\n    },\n  ],\n};\n```\n\n## Why?\n\nWhy do you need this plugin? The fantastic `gatsby-plugin-image` tool only works\non _relative_ paths to locally stored images. This lets you use it on images\nfrom an API with an _absolute_ path. For example, look at these two response\nfrom one GraphQL query:\n\n_Query_\n\n```graphql\nallMyNodes {\n    edges {\n      node {\n        id\n        imageUrl\n      }\n    }\n  }\n```\n\n_Absolute imageUrl NOT available to `gatsby-plugin-image`_\n\n```javascript\nallMyNodes: [\n  {\n    node: {\n      id: 123,\n      imageUrl: 'http://remoteimage.com/url.jpg',\n    },\n  },\n];\n```\n\n_Relative imageUrl IS available to `gatsby-plugin-image`_\n\n```javascript\nallMyNodes: [\n  {\n    node: {\n      id: 123,\n      imageUrl: 'localImages/url.jpg',\n    },\n  },\n];\n```\n\nIf you don't control the API that you are hitting (many third party APIs return\na field with a string to an absolute path for an image), this means those image\naren't run through `gatsby-plugin-image` and you lose all of the benefits.\n\nTo get the images and make them available for the above example, follow the\ninstall instructions and your config should look like this:\n\n```javascript\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-plugin-remote-images`,\n      options: {\n        nodeType: 'MyNodes',\n        imagePath: 'imageUrl',\n        // OPTIONAL: Name you want to give new image field on the node.\n        // Defaults to 'localImage'.\n        name: 'allItemImages',\n      },\n    },\n  ],\n};\n```\n\nNow, if we query `allMyNodes` we can query as we would any `gatsby-plugin-image`\nnode:\n\n```graphql\nallMyNodes {\n  edges {\n    node {\n      localImage {\n        childImageSharp {\n          gatsbyImageData(width: 400)\n        }\n      }\n    }\n  }\n}\n```\n\n**Note:** Many Gatsby source plugins already do this work for you under the\nhood. So if you are working with a common CMS's Gatsby plugin, odds are that\n_you don't need this!_\n\n## Common Issues\n\n### `gatsby-source-graphql`\n\nDue to the way `gatsby-source-graphql` creates nodes, it is currently impossible\nfor any transformer type plugin to traverse the data from that plugin.\n[Please read this issue for explanation](https://github.com/gatsbyjs/gatsby/issues/8404).\nAs soon as that as fixed in `gatsby-source-graphql`, this plugin will be tested\nto make sure it works with it as well.\n\n### Traversing objects with arrays\n\nSince some GraphQL APIs will send back objects with nested arrays where your\ntarget data lives, `gatsby-plugin-remote-images` also supports traversing\nobjects that have arrays at arbitrary depths. To opt in to this feature, add an\narray literal, `[]`, to the end of the node you want to indicate is an array.\n\nGiven an object structure like this:\n\n```javascript\nallMyNodes {\n  nodes: [\n    {\n      imageUrl: 'https://...'\n    },\n    ...\n  ]\n}\n```\n\nTo get the images and make them available for the above example, your config\nshould look like this:\n\n```javascript\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-plugin-remote-images`,\n      options: {\n        nodeType: 'MyNodes',\n        imagePath: 'nodes[].imageUrl',\n      },\n    },\n  ],\n};\n```\n\nNow, if we query `allMyNodes` we can query as we would any `gatsby-plugin-image`\nnode:\n\n```graphql\nallMyNodes {\n  nodes {\n    localImage {\n      childImageSharp {\n        gatsbyImageData(width: 400)\n      }\n    }\n  }\n}\n```\n\n**Note:** While `lodash .get` doesn't natively support this syntax, it is still\nused to traverse the object structure, so\n[the documentation for `.get`](https://lodash.com/docs/4.17.11#get) still\napplies in full.\n\n### Handling an Array of Image URLs\n\nIn case your API offers an image path to an _array_ of images, instead of just\none, there is a way to handle that with the plugin. For instances where there is\nan array somewhere along the _path to_ the images,\n[see above](#traversing-objects-with-arrays).\n\nFor example, you API returns:\n\n```javascript\n// MyNode\n{\n  date: '1-1-2010',\n  category: 'cats'\n  // Note that here there are multiple images at the *leaf* node where the images are found.\n  images: [\n    'https://.../image1.png',\n    'https://.../image2.png'\n  ]\n}\n```\n\nTo make your local image field an array of these images, adjust your config\naccordingly:\n\n```javascript\n {\n   resolve: `gatsby-plugin-remote-images`,\n   options: {\n     nodeType: 'MyNodes',\n     // Making this plural (optional).\n     name: 'localImages',\n     // Path to the leaf node.\n     imagePath: 'images',\n     // Set type to array.\n     type: 'array'\n   }\n}\n```\n\nNow, if we query `allMyNodes` we can query as we would any `gatsby-plugin-image`\nnode, but now `localImage` (or `localImages` as in the example above) we would\nget an array of Gatsby images, instead of just one.\n\n```graphql\nallMyNodes {\n  nodes {\n    localImages {\n      childImageSharp {\n        gatsbyImageData(width: 400)\n      }\n    }\n  }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraysonhicks%2Fgatsby-plugin-remote-images","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraysonhicks%2Fgatsby-plugin-remote-images","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraysonhicks%2Fgatsby-plugin-remote-images/lists"}