Registry / web-framework / gatsby-remark-images

gatsby-remark-images

library7.16.0jsnpmunverified

gatsby-remark-images is a Gatsby plugin designed to enhance markdown-embedded images, making them responsive and optimized for production builds. It functions by processing images within markdown files through `gatsby-transformer-remark`, generating multiple width versions and setting `srcset` and `sizes` attributes for efficient, bandwidth-aware loading. A key feature is its "blur-up" technique, which uses a small, lightweight placeholder image that quickly loads and then transitions to the full-resolution image, improving perceived performance and preventing layout shifts. The plugin is currently at version `7.16.0` and is an integral part of the actively maintained Gatsby ecosystem, with updates often coinciding with new Gatsby framework releases. It critically depends on `gatsby-plugin-sharp` for its underlying image processing capabilities, enabling advanced optimizations like WebP conversion and quality compression.

web-framework

npm install gatsby-remark-images

github ↗package ↗

INSTALL

IMPORT

SIG · GATSBY-REMARK-IMAG

gatsby-remark-images

web-frameworkjavascriptv7.16.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

gatsby-remark-images

✓ plugins: [ `gatsby-plugin-sharp`, { resolve: `gatsby-transformer-remark`, options: { plugins: [ { resolve: `gatsby-remark-images`, options: { maxWidth: 590 } } ] } } ]

✗ import { GatsbyRemarkImages } from 'gatsby-remark-images'; // This plugin is not imported directly as a module.

This plugin is configured within your `gatsby-config.js` file as an entry in the `plugins` array, specifically nested under `gatsby-transformer-remark`. It does not expose direct JavaScript exports for use in components or utilities.

Markdown Image Syntax

✓ ![Alt text here](./image.jpg) ![GATSBY_EMPTY_ALT](./image.png)

✗ ![External Image](https://example.com/image.jpg) // External images are not processed by this plugin.

Images must be referenced with relative paths within your markdown files to be processed by `gatsby-remark-images`. The special keyword `GATSBY_EMPTY_ALT` can be used to generate an empty `alt=""` attribute.

This configuration snippet shows how to integrate `gatsby-remark-images` into your `gatsby-config.js`. It enables responsive image processing for markdown files, leveraging `gatsby-plugin-sharp` and setting a `maxWidth` for optimized image generation.

// In your gatsby-config.js module.exports = { plugins: [ `gatsby-plugin-sharp`, // Required for image processing { resolve: `gatsby-transformer-remark`, options: { plugins: [ { resolve: `gatsby-remark-images`, options: { // It's important to specify the maxWidth (in pixels) of // the content container as this plugin uses this as the // base for generating different widths of each image. maxWidth: 590, linkImagesToOriginal: true // Optional: links processed images to their original source } } ] } } ] };

Debug

Known issues

breakingThis plugin, aligned with Gatsby v5, requires Node.js version 18 or higher. Deployments or local development environments running on older Node.js versions will fail.

fix

Upgrade Node.js to version 18.0.0 or higher. For Gatsby v5, ensure Node.js is within the `>=18.0.0 <26` range specified by the package's engines.

affects: >=7.0.0

breaking`gatsby-remark-images` version 7.x requires Gatsby v5 (`^5.0.0-next`) as a peer dependency. Using it with Gatsby v4 or earlier will lead to compatibility issues or failures.

fix

Ensure your project's `package.json` specifies `gatsby: ^5.0.0-next` and `gatsby-plugin-sharp: ^5.0.0-next`. Upgrade Gatsby and `gatsby-plugin-sharp` if necessary.

affects: >=7.0.0

gotcha`gatsby-remark-images` relies entirely on `gatsby-plugin-sharp` for image processing. If `gatsby-plugin-sharp` is not installed and configured, or if there are issues with its native dependencies, `gatsby-remark-images` will not function.

fix

Verify `gatsby-plugin-sharp` is installed (`npm install gatsby-plugin-sharp`) and correctly listed in `gatsby-config.js` *before* `gatsby-transformer-remark` and `gatsby-remark-images`.

affects: *

gotchaFailing to set an appropriate `maxWidth` in the plugin options, or setting it too low/high, can lead to sub-optimal responsive image generation or unnecessarily large images. The `maxWidth` should reflect the maximum width your markdown content area will occupy.

fix

Carefully determine the `maxWidth` for your content area and configure it in `gatsby-config.js` options for `gatsby-remark-images`. For example: `options: { maxWidth: 800 }`.

affects: *

gotcha`gatsby-remark-images` only processes images referenced by *relative paths* within markdown files. Absolute paths or external URLs will be ignored by the plugin, appearing as regular images without responsiveness.

fix

Ensure all images intended for processing are stored locally within your project and referenced using paths relative to the markdown file they are embedded in. For external images, consider `gatsby-remark-external-links` or similar plugins.

affects: *

gotchaGatsby and its ecosystem plugins, including `gatsby-remark-images`, occasionally receive dependency updates to address security vulnerabilities (e.g., `body-parser`, `multer` were updated in recent Gatsby core releases). Running outdated versions can expose your project to known issues.

fix

Regularly update `gatsby`, `gatsby-plugin-sharp`, and `gatsby-remark-images` to their latest stable versions to benefit from security patches and performance improvements.

affects: <7.16.0

Errors

Common errors & fixes

Error: Plugin 'gatsby-remark-images' not found.

The `gatsby-remark-images` package is not installed or incorrectly referenced in `gatsby-config.js`, or `gatsby-transformer-remark` is missing.

fix

Ensure you have `gatsby-remark-images` and `gatsby-transformer-remark` installed (`npm install gatsby-remark-images gatsby-transformer-remark`) and correctly configured in your `gatsby-config.js` under the `plugins` array.

Error: GraphQL error: Cannot query field "childImageSharp" on type "MarkdownRemark".

This error typically indicates that `gatsby-plugin-sharp` is not installed, not configured, or there's an issue with your `gatsby-config.js` order, preventing image nodes from being transformed.

fix

Verify `gatsby-plugin-sharp` is installed (`npm install gatsby-plugin-sharp`) and configured *before* `gatsby-transformer-remark` in your `gatsby-config.js`.

The engine "node" is incompatible with this module. Expected version "20 || >=22". Got "18.6.0"

Your Node.js environment does not meet the minimum or compatible version requirements of Gatsby or its plugins (such as `gatsby-remark-images`).

fix

Upgrade your Node.js environment to a supported version. For Gatsby v5, this typically means Node.js 18 or higher. Use a version manager like `nvm` (`nvm install 18 && nvm use 18`) to manage Node.js versions.

Markdown images are not responsive; they load as original size or cause layout shifts.

This usually means `gatsby-remark-images` is not correctly processing the images due to improper configuration (e.g., `maxWidth` missing, wrong image paths) or a conflict with other plugins/CSS.

fix

Double-check your `gatsby-config.js` for `gatsby-remark-images` options, especially `maxWidth`. Ensure markdown image paths are relative. Also, inspect your browser's developer tools for any CSS overrides that might be affecting the plugin's generated image wrappers.

Upgrade

Version history

7.16.0latest on npm

Audit

Dependencies

gatsbyrequiredCore Gatsby framework, required for any Gatsby plugin. This plugin is tightly coupled with Gatsby's node API.

gatsby-plugin-sharprequiredImage processing engine. gatsby-remark-images delegates all image manipulation tasks (resizing, generating multiple formats, blur-up) to gatsby-plugin-sharp.

gatsby-transformer-remarkrequiredThis plugin is designed to work specifically with gatsby-transformer-remark, which processes Markdown files into HTML and allows other remark plugins to hook into the transformation.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/gatsbyjs/gatsby ↗

packagehttps://www.npmjs.com/package/gatsby-remark-images ↗