fix(assets): pass through images Sharp cannot decode instead of crashing

[maximslo]

This is a fix for #16267.

Changes

• Wrapped Sharp's metadata() call in a try/catch. When Sharp cannot decode an image (e.g. animated AVIF sequences), the original buffer is returned unmodified instead of crashing the build. The file is still hashed for cache-busting; only transformation is skipped.
  • Those bytes then get written to _astro/filename.avif in the build output. The <img> tag in the HTML still points to that file; the browser receives the original animated AVIF directly.
  • The only difference from a normal pass-through (like public/) is that Astro still hashes the filename for cache-busting. The content is identical to the source file.

Testing

Run the new test directly:
pnpm run test:match "animated avif"

OR manually:

1. Add your own animated AVIF to packages/astro/test/fixtures/core-image-ssg/src/assets/
2. Reference it via <Image> in a page.
3. Run pnpm build

The build should complete and the file should appear in _astro/ unmodified. Previously this would crash with CouldNotTransformImage.

Note: future support for AVIF would require...

The groundwork is already partly there. pages: -1 is the Sharp flag that loads all frames of an animated image (already set) BUT needed:

• Sharp/libvips version support. The crash itself (metadata() throwing) means the current Sharp (0.34.5) can't decode animated AVIF metadata. This is a libvips limitation, newer builds of libvips with libaom support can handle it. Depends on Sharp upstream.

• Format detection. AVIF uses the HEIF container, so Sharp reports animated AVIF as format: 'heif', not avif. The animated GIF → WebP path in sharp.ts would need an equivalent:

if (transform.format === 'webp' && (format === 'gif' || format === 'heif')) {
    result.webp({ ...encoderOptions, loop: 0 });
}

• Animated AVIF output. result.avif() with pages: -1 already loaded should output animated AVIF, but only once Sharp can decode it in the first place.

So this pass-through fix is fine short-term. Full support is blocked on Sharp's libvips gaining animated AVIF decode support.

Docs

/cc @withastro/maintainers-docs for feedback!

[changeset-bot]

🦋 Changeset detected

Latest commit: 0d3f832

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codspeed-hq]

Merging this PR will not alter performance

✅ 18 untouched benchmarks

---

_{Comparing maximslo:fix/animated-avif-passthrough (0d3f832) with main (1058428)}

[fkatsuhiro]

@maximslo
Thank you for your PR!
It seems faild some tests. I think it related new imolementation of this PR.
Will you check this? And I recomend you to create test for this issue. Thank you!

[maximslo]

@fkatsuhiro Added! You can run it with pnpm run test:match "animated avif"

I believe all earlier failing tests were MiniflareCoreError [ERR_RUNTIME_FAILURE], the Cloudflare Workers runtime (infrastructure/environment issue with the CI runner, not anything touched by my change)

[fkatsuhiro]

@maximslo san
Thank you for your updating!
I think it looks good to me. But I forgot to tell you to create changeset file. Sorry.

You can create changeset file via command pnpm changeset. And select your updated package and write summery of your change. Could you update your PR?
Reference: https://contribute.docs.astro.build/docs-for-code-changes/changesets/#tips-and-examples

Sorry for bothering.

[fkatsuhiro]

Thanks for your updating!
Looks good to me! Thanks!