Using Gatsby StaticImage for Optimized Asset Delivery

Desired outcome

Add a locally stored image to a Gatsby page so that the build pipeline creates multiple resized versions, serves WebP/Avif when supported, and shows a low‑quality blur placeholder while the image loads.

Prerequisites

1. A Gatsby project (v4 or later) with Node.js ≥14 installed.
2. Access to the project’s root directory to run npm commands.
3. An image file you want to display, placed inside src/images/ (or any folder under src/).

Procedure

1. Install the required plugins from the project root:

npm install gatsby-plugin-image gatsby-plugin-sharp

2. Add the plugins to gatsby-config.js. Ensure gatsby-plugin-sharp comes before gatsby-plugin-image in the array:

module.exports = {
  plugins: [
    'gatsby-plugin-sharp',
    'gatsby-plugin-image',
    // other plugins …
  ]
};

3. Import and use the StaticImage component in a page or component. Replace your-image.jpg with the actual file name:

import { StaticImage } from 'gatsby-plugin-image'

export default function MyPage() {
  return (
    
      
    
  )
}

4. Run the development server to see the result:

npm run develop

5. For a production build, execute:

npm run build

npm run serve

Expected checks

1. Open the page in a browser, right‑click the image and choose "Inspect". Verify that the <img> element contains a srcset attribute with multiple URLs (e.g., ...-400.webp, ...-800.webp).
2. Open the Network tab, reload the page, and filter by "Img". Confirm that the requested image URL ends with .webp or .avif (depending on browser support).
3. Observe that a blurred version of the image appears briefly before the sharp image loads; this is the LQIP placeholder generated by the plugin.

Recovery options

If the image does not appear or the build fails:

• Check the file path in the src prop; an incorrect relative path triggers a build‑time error, not a 404.
• Ensure sharp is installed correctly; on some platforms you may need to run npm rebuild sharp or install system dependencies (e.g., libvips on Linux).
• To revert, remove the StaticImage usage, delete the plugin entries from gatsby-config.js, run gatsby clean, and reinstall the previous state.