gatsby-plugin-image vs gatsby-transformer-sharp for CI builds with bandwidth limits and Sharp dependency concerns

Answer to the Core Question

Which plugin offers the best trade‑off for a CI environment that may lack vips libraries and has limited download bandwidth?

For a project that already uses GraphQL image queries, gatsby‑plugin‑image is the recommended choice. It relies on gatsby-plugin-sharp for the actual image processing, but you can avoid the heavy Sharp install in CI by:

• Using a non‑Alpine base image (e.g., node:20-bullseye-slim) that ships pre‑built Sharp binaries.
• Pre‑building the image assets locally or in a larger CI image and committing the generated files and the .cache directory to the repo.
• Setting GATSBY_SHARP_IGNORE_DANGEROUS_OPTS=1 so the build skips the Sharp build step when the cache is present.
• Enabling modern formats with GATSBY_IMAGE_FORMATS=webp,avif if you want WebP/AVIF output.

In contrast, gatsby-transformer-sharp can be faster for very small image sets because it only generates a handful of sizes, but it requires manual configuration of srcset sizes and does not support AVIF out of the box. It also still needs Sharp, so the same Alpine dependency issue applies.

Can gatsby-transformer-sharp be extended to match gatsby-plugin-image?

Yes, but it requires a hybrid setup:

1. Use gatsby-transformer-sharp to create responsive image nodes.
2. Wrap those nodes with the GatsbyImage component from gatsby-plugin-image (or the legacy Img component) to get lazy loading and modern format support.
3. Configure gatsby-config.js to expose AVIF/WebP via gatsby-plugin-sharp options.

This hybrid approach still incurs Sharp processing at build time, so the benefits are limited if your CI cannot download the binaries quickly.

Practical Steps for Your CI Pipeline

# Example Dockerfile for a non‑Alpine image
FROM node:20-bullseye-slim
WORKDIR /app
COPY package.json yarn.lock .
RUN yarn install --frozen-lockfile
COPY . .

# Pre‑build images locally (outside CI) and commit the .cache folder
# Or run the full build once in a larger image and commit the .cache
RUN yarn gatsby clean && yarn gatsby build

# In CI, skip Sharp if cache exists
ENV GATSBY_SHARP_IGNORE_DANGEROUS_OPTS=1
RUN yarn gatsby build

Verification Checklist

• Run npx gatsby clean && gatsby build on the chosen base image and confirm the build finishes < 30 s.
• Check the public directory for image-*.avif and image-*.webp files to verify modern format support.
• Ensure the .cache directory is preserved between CI runs to avoid re‑processing.

Missing Diagnostic Detail

To fine‑tune this recommendation, could you confirm whether you plan to commit pre‑built image assets or prefer to keep the build entirely in CI? That choice will influence whether the Alpine base image is viable or a non‑Alpine image is required.