Statamic Graphql Responsive Images Laravel Package

Getting Started

• Install with Composer: composer require legrisch/statamic-graphql-responsive-images. The package depends on Statamic’s GraphQL addon, so make sure statamic/graphql is installed and your GraphQL endpoint is working before wiring up the responsive image field.
• Read the README’s GraphQL schema example first, then inspect the package’s registered GraphQL type/resolver under src/. The addon is primarily a thin adapter between the Responsive Images fieldtype and GraphQL, so the schema is the main contract you need to understand.
• The first practical use case is a page entry with a hero image field: expose that field in your GraphQL schema as the package’s responsive image type, query src, srcset, sizes, and dimensions, then render the strings directly in an <img> tag.
• v1.4.1 is a README/schema documentation update only. There are no migration steps or runtime changes to account for when coming from v1.4.0.

query Page($slug: String!) {
  entry(slug: $slug) {
    title
    hero: responsiveImage(field: "hero_image") {
      src
      srcset
      sizes
      width
      height
    }
  }
}

Implementation Patterns

• Define reusable GraphQL fragments for the responsive image payload and spread them across entries, assets, and nested Bard/Replicator sets. This keeps field selection consistent and avoids duplicating the same image fields in every type.
• If a type has multiple responsive image fields, use GraphQL aliases (hero: ..., thumbnail: ...) so the response shape stays readable and frontend mapping remains explicit.
• Use @include(if: $withImages) or separate list/detail queries when you only need image data on detail pages. srcset strings can be large, and GraphQL will still transfer the whole string even if the frontend only uses src.
• On the frontend, treat srcset and sizes as opaque strings produced by the fieldtype. Pass them through to <img> and keep src as the fallback; do not try to parse or reconstruct them unless you have a specific art-direction requirement.
• For <picture> or art-direction layouts, model each image as its own field/alias rather than trying to infer breakpoint variants from a single srcset string.
• Cache GraphQL query results at the CDN or application layer where appropriate. Responsive image URLs are usually stable until the asset or field configuration changes, so they are good candidates for Statamic/GraphQL caching directives.
• In multisite setups, query with the correct site argument and verify that asset URLs resolve to the expected domain or path. Do not assume the default site’s URLs are valid everywhere.
• Test queries against the actual GraphQL endpoint rather than only unit-testing fieldtype output; schema registration and nullability issues usually show up at query time.

Gotchas and Tips

• Clear Statamic and GraphQL caches after changing schema files or adding the field to a type. If the field does not appear in introspection, stale schema cache is the first thing to check.
• Missing or deleted assets can produce null image data. Keep responsive image fields nullable in your schema and guard for nulls in frontend components.
• The addon exposes image data; it does not generate missing image transformations. If a breakpoint or size is absent, fix the underlying fieldtype/asset configuration and re-save the asset rather than expecting GraphQL to create it.
• Confirm the stored field shape in your version. Some responsive image fields resolve to a single object, while others may resolve to a list. Query the type in GraphQL introspection before assuming a single src/srcset object.
• Watch for field-name collisions with Statamic’s Asset type (url, width, height). Use aliases or distinct field names in your schema to keep the frontend mapping unambiguous.
• Avoid requesting srcset in broad list queries unless the UI needs it; the payload can grow quickly across many entries.
• If you upgrade from an older release, check the v1.4.0 changes as well as v1.4.1. The latest release itself only updates README schema documentation, so any behavioral changes came earlier.
• Extension point: prefer extending the GraphQL schema with derived fields or custom resolvers over forking the addon. If you need custom image metadata, add it at the schema/resolver layer and keep the package’s fieldtype adapter intact.