[PR #1021] [MERGED] fix: add hydration-level onError replay in next/image via useLayoutEffect #1025

New issue

Closed

opened 2026-05-06 13:11:37 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 13:11:37 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/1021
Author: @Divkix
Created: 5/2/2026
Status: ✅ Merged
Merged: 5/2/2026
Merged by: @james-elicx

Base: main ← Head: fix/1007-next-image-hydration-onerror-replay

📝 Commits (5)

c9a14aa fix: add hydration-level onError replay in next/image via useLayoutEffect (#1007)
39835c3 fix: address PR review feedback for next/image onError hydration replay (#1007)
770249c fix(next/image): address PR review — extract helper, clean deps, add comment
2b5cbf5 fix: guard onLoad replay with naturalWidth > 0, clean deps (#1007)
a7ce561 fix: port Next.js useMergedRef hook for next/image ref merging

📊 Changes

3 files changed (+265 additions, -3 deletions)

View changed files

📝 packages/vinext/src/shims/image.tsx (+122 -3)
➕ packages/vinext/src/shims/use-merged-ref.ts (+57 -0)
📝 tests/shims.test.ts (+86 -0)

📄 Description

Fixes #1007

Summary

Ports the upstream Next.js hydration replay pattern from vercel/next.js#93209
Adds useNonWarningLayoutEffect + img.src = img.src to re-trigger the error trajectory when an image fails before React hydration completes (e.g. during SSR streaming or initial HTML parse)
Adds mergedRef to capture the underlying img element and forward the parent ref simultaneously
Forwards ref to @unpic/react Image elements (supports ref forwarding)
Adds SSR rendering regression tests for onError, onLoad+onError, ref forwarding, and loader paths

Test plan

Added 5 new SSR rendering tests in tests/shims.test.ts covering onError, onLoad+onError, ref forwarding, and loader path
Full test suite: 4668 passed (1 pre-existing unrelated afterAll timeout in pages-router.test.ts)
Lint, format, and typecheck all pass

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/cloudflare/vinext/pull/1021 **Author:** [@Divkix](https://github.com/Divkix) **Created:** 5/2/2026 **Status:** ✅ Merged **Merged:** 5/2/2026 **Merged by:** [@james-elicx](https://github.com/james-elicx) **Base:** `main` ← **Head:** `fix/1007-next-image-hydration-onerror-replay` --- ### 📝 Commits (5) - [`c9a14aa`](https://github.com/cloudflare/vinext/commit/c9a14aa44ff2f9cc5539414a20ff3ba4f544c712) fix: add hydration-level onError replay in next/image via useLayoutEffect (#1007) - [`39835c3`](https://github.com/cloudflare/vinext/commit/39835c3522a9c6228b1c082243c71afd7839c3ce) fix: address PR review feedback for next/image onError hydration replay (#1007) - [`770249c`](https://github.com/cloudflare/vinext/commit/770249c9eb6abad2697c42d7d6defb52d8f7b47d) fix(next/image): address PR review — extract helper, clean deps, add comment - [`2b5cbf5`](https://github.com/cloudflare/vinext/commit/2b5cbf5eaa1a2814ac74b1caefd12a08ffdae18b) fix: guard onLoad replay with naturalWidth > 0, clean deps (#1007) - [`a7ce561`](https://github.com/cloudflare/vinext/commit/a7ce5618becd0e5673bea2c0461cb3cfc1c55a66) fix: port Next.js useMergedRef hook for next/image ref merging ### 📊 Changes **3 files changed** (+265 additions, -3 deletions) <details> <summary>View changed files</summary> 📝 `packages/vinext/src/shims/image.tsx` (+122 -3) ➕ `packages/vinext/src/shims/use-merged-ref.ts` (+57 -0) 📝 `tests/shims.test.ts` (+86 -0) </details> ### 📄 Description Fixes #1007 ## Summary - Ports the upstream Next.js hydration replay pattern from vercel/next.js#93209 - Adds `useNonWarningLayoutEffect` + `img.src = img.src` to re-trigger the error trajectory when an image fails before React hydration completes (e.g. during SSR streaming or initial HTML parse) - Adds `mergedRef` to capture the underlying img element and forward the parent ref simultaneously - Forwards ref to `@unpic/react` Image elements (supports ref forwarding) - Adds SSR rendering regression tests for onError, onLoad+onError, ref forwarding, and loader paths ## Test plan - Added 5 new SSR rendering tests in `tests/shims.test.ts` covering onError, onLoad+onError, ref forwarding, and loader path - Full test suite: 4668 passed (1 pre-existing unrelated `afterAll` timeout in `pages-router.test.ts`) - Lint, format, and typecheck all pass --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>