[PR #385] [CLOSED] fix(image): align next/image API with Next.js 16.0.0 #533

New issue

Closed

opened 2026-05-06 13:08:36 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 13:08:36 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/385
Author: @Divkix
Created: 3/9/2026
Status: ❌ Closed

Base: main ← Head: fix/align-image-api-nextjs-16

📝 Commits (10+)

bef7956 fix(image): align next/image API surface with Next.js 16.0.0
e75dcf5 fix(image): address PR #385 review feedback
6409016 fix(image): remove dead allowedQualities param, fix remote data:image/ placeholder
00283e6 fix(image): add missing fetchPriority to custom loader path, add AVIF/preload tests
4c7efb8 fix(image): align next/image contract with next 16
122d968 fix(image): address lint warnings
9161747 fix(image): stabilize parity test fallout
af91d37 fix(image): tighten optimizer security
f49db87 fix(image): address PR review feedback
e8b4b08 test(image): add security-critical test coverage for image optimization

📊 Changes

27 files changed (+6789 additions, -1306 deletions)

View changed files

📝 .agents/skills/migrate-to-vinext/references/compatibility.md (+25 -25)
📝 README.md (+30 -30)
📝 examples/app-router-cloudflare/worker/index.ts (+25 -3)
📝 packages/vinext/src/config/next-config.ts (+157 -15)
📝 packages/vinext/src/deploy.ts (+35 -9)
📝 packages/vinext/src/global.d.ts (+28 -1)
📝 packages/vinext/src/index.ts (+42 -1)
📝 packages/vinext/src/server/image-optimization.ts (+652 -188)
📝 packages/vinext/src/server/prod-server.ts (+69 -61)
➕ packages/vinext/src/shims/image-blur-svg.ts (+36 -0)
📝 packages/vinext/src/shims/image-config.ts (+133 -67)
📝 packages/vinext/src/shims/image.tsx (+807 -415)
📝 packages/vinext/src/shims/next-shims.d.ts (+22 -38)
📝 tests/__snapshots__/entry-templates.test.ts.snap (+1 -1)
📝 tests/deploy.test.ts (+1 -1)
📝 tests/fixtures/ecosystem/next-intl/vite.config.ts (+6 -0)
📝 tests/fixtures/ecosystem/nuqs/vite.config.ts (+11 -0)
📝 tests/fixtures/ecosystem/validator/vite.config.ts (+3 -0)
➕ tests/image-blur-svg.test.ts (+166 -0)
📝 tests/image-component.test.ts (+1262 -357)

...and 7 more files

📄 Description

Pre-requisite for #364 — This PR aligns the API surface; #364 adds Sharp-based build-time image optimization on top.

Closes #386

Summary

Aligns vinext's next/image implementation with the Next.js 16.0.0 API surface. Any library or app code written against Next.js 16's image API should now work on vinext without modification.

Changes

StaticImageData: Add blurWidth and blurHeight optional fields
imageSizes default: Remove 16 → [32, 48, 64, 96, 128, 256, 384] (matches Next.js 16)
contentDispositionType default: "inline" → "attachment" (security — prevents XSS via image endpoint)
preload prop: New prop replacing deprecated priority (both now trigger loading="eager" + fetchPriority="high")
qualities config: Add images.qualities support with findClosestQuality() rounding and server-side validation
AVIF quality offset: Apply Math.max(quality - 20, 1) for AVIF in handleImageOptimization (matches Next.js)
Deprecated props: Accept and ignore onLoadingComplete, layout, objectFit, objectPosition, lazyBoundary, lazyRoot
PlaceholderValue type: Widen to "blur" | "empty" | \data:image/${string}``
width/height type: Widen to number | \${number}`` with automatic string→number parsing
Type exports: Export StaticRequire, StaticImport, ImageLoaderProps, ImageProps
allowedQualities: Add quality validation to parseImageParams

What's deferred

localPatterns, minimumCacheTTL, loader/loaderFile global config, disableStaticImages, maximumRedirects, dangerouslyAllowLocalIP, images.unoptimized global, @hapi/accept negotiation, and strict w/q required params — these are either not yet needed or would break existing vinext users.

Test plan

pnpm test tests/image-component.test.ts — 41 tests pass (new tests for preload, deprecated props, string dims, data placeholder, StaticImport, type exports)
pnpm test tests/image-imports.test.ts — 20 tests pass
pnpm test tests/shims.test.ts — 577 pass (updated DEFAULT_IMAGE_SIZES and contentDisposition default assertions)
pnpm test tests/deploy.test.ts — 193 tests pass
pnpm test tests/image-config.test.ts — 33 tests pass
pnpm run typecheck — no new errors (pre-existing __NEXT_DATA__ errors only)
pnpm run lint — clean

_{🔄 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/385 **Author:** [@Divkix](https://github.com/Divkix) **Created:** 3/9/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/align-image-api-nextjs-16` --- ### 📝 Commits (10+) - [`bef7956`](https://github.com/cloudflare/vinext/commit/bef7956d63091a502c1278ca670d9ae0f5eff4b3) fix(image): align next/image API surface with Next.js 16.0.0 - [`e75dcf5`](https://github.com/cloudflare/vinext/commit/e75dcf5547a8f554367c06bfa114d908da9957a4) fix(image): address PR #385 review feedback - [`6409016`](https://github.com/cloudflare/vinext/commit/64090167f0ae5d71bc7bc2e5521ef11d4b839c40) fix(image): remove dead allowedQualities param, fix remote data:image/ placeholder - [`00283e6`](https://github.com/cloudflare/vinext/commit/00283e65ecce2224645a1ee8b0cb3b07d507d37b) fix(image): add missing fetchPriority to custom loader path, add AVIF/preload tests - [`4c7efb8`](https://github.com/cloudflare/vinext/commit/4c7efb8d501d95a63aaaa7f38b9e81d31cf4c081) fix(image): align next/image contract with next 16 - [`122d968`](https://github.com/cloudflare/vinext/commit/122d96885619715a40cd26bc987182a6297cacc9) fix(image): address lint warnings - [`9161747`](https://github.com/cloudflare/vinext/commit/9161747309fbe2afa97103e3f60e5e0a1d56b5a8) fix(image): stabilize parity test fallout - [`af91d37`](https://github.com/cloudflare/vinext/commit/af91d37b3be7868f400bbe672a2e0050781c83b9) fix(image): tighten optimizer security - [`f49db87`](https://github.com/cloudflare/vinext/commit/f49db8701f0fc20c6f4a8de84e52b38461cdd44f) fix(image): address PR review feedback - [`e8b4b08`](https://github.com/cloudflare/vinext/commit/e8b4b08cc9ae8dc3540d673762315d6e1bfbf896) test(image): add security-critical test coverage for image optimization ### 📊 Changes **27 files changed** (+6789 additions, -1306 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/migrate-to-vinext/references/compatibility.md` (+25 -25) 📝 `README.md` (+30 -30) 📝 `examples/app-router-cloudflare/worker/index.ts` (+25 -3) 📝 `packages/vinext/src/config/next-config.ts` (+157 -15) 📝 `packages/vinext/src/deploy.ts` (+35 -9) 📝 `packages/vinext/src/global.d.ts` (+28 -1) 📝 `packages/vinext/src/index.ts` (+42 -1) 📝 `packages/vinext/src/server/image-optimization.ts` (+652 -188) 📝 `packages/vinext/src/server/prod-server.ts` (+69 -61) ➕ `packages/vinext/src/shims/image-blur-svg.ts` (+36 -0) 📝 `packages/vinext/src/shims/image-config.ts` (+133 -67) 📝 `packages/vinext/src/shims/image.tsx` (+807 -415) 📝 `packages/vinext/src/shims/next-shims.d.ts` (+22 -38) 📝 `tests/__snapshots__/entry-templates.test.ts.snap` (+1 -1) 📝 `tests/deploy.test.ts` (+1 -1) 📝 `tests/fixtures/ecosystem/next-intl/vite.config.ts` (+6 -0) 📝 `tests/fixtures/ecosystem/nuqs/vite.config.ts` (+11 -0) 📝 `tests/fixtures/ecosystem/validator/vite.config.ts` (+3 -0) ➕ `tests/image-blur-svg.test.ts` (+166 -0) 📝 `tests/image-component.test.ts` (+1262 -357) _...and 7 more files_ </details> ### 📄 Description > **Pre-requisite for #364** — This PR aligns the API surface; #364 adds Sharp-based build-time image optimization on top. Closes #386 ## Summary Aligns vinext's `next/image` implementation with the Next.js 16.0.0 API surface. Any library or app code written against Next.js 16's image API should now work on vinext without modification. ### Changes - **StaticImageData**: Add `blurWidth` and `blurHeight` optional fields - **imageSizes default**: Remove `16` → `[32, 48, 64, 96, 128, 256, 384]` (matches Next.js 16) - **contentDispositionType default**: `"inline"` → `"attachment"` (security — prevents XSS via image endpoint) - **`preload` prop**: New prop replacing deprecated `priority` (both now trigger `loading="eager"` + `fetchPriority="high"`) - **`qualities` config**: Add `images.qualities` support with `findClosestQuality()` rounding and server-side validation - **AVIF quality offset**: Apply `Math.max(quality - 20, 1)` for AVIF in `handleImageOptimization` (matches Next.js) - **Deprecated props**: Accept and ignore `onLoadingComplete`, `layout`, `objectFit`, `objectPosition`, `lazyBoundary`, `lazyRoot` - **PlaceholderValue type**: Widen to `"blur" | "empty" | \`data:image/${string}\`` - **width/height type**: Widen to `number | \`${number}\`` with automatic string→number parsing - **Type exports**: Export `StaticRequire`, `StaticImport`, `ImageLoaderProps`, `ImageProps` - **allowedQualities**: Add quality validation to `parseImageParams` ### What's deferred `localPatterns`, `minimumCacheTTL`, `loader`/`loaderFile` global config, `disableStaticImages`, `maximumRedirects`, `dangerouslyAllowLocalIP`, `images.unoptimized` global, `@hapi/accept` negotiation, and strict `w`/`q` required params — these are either not yet needed or would break existing vinext users. ## Test plan - [x] `pnpm test tests/image-component.test.ts` — 41 tests pass (new tests for preload, deprecated props, string dims, data placeholder, StaticImport, type exports) - [x] `pnpm test tests/image-imports.test.ts` — 20 tests pass - [x] `pnpm test tests/shims.test.ts` — 577 pass (updated DEFAULT_IMAGE_SIZES and contentDisposition default assertions) - [x] `pnpm test tests/deploy.test.ts` — 193 tests pass - [x] `pnpm test tests/image-config.test.ts` — 33 tests pass - [x] `pnpm run typecheck` — no new errors (pre-existing `__NEXT_DATA__` errors only) - [x] `pnpm run lint` — clean --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>