@qzsy/vinext 0.1.11 → 0.1.80

package/dist/entries/app-rsc-entry.d.ts

@@ -43,7 +43,8 @@ type AppRouterConfig = {
    */
   reactMaxHeadersLength?: number; /** Maximum in-memory cache size in bytes. 0 disables the default memory cache. */
   cacheMaxMemorySize?: number; /** Inline app CSS into production HTML (from experimental.inlineCss). */
-  inlineCss?: boolean; /** Enables Next.js Cache Components semantics for App Router document HTML. */
+  inlineCss?: boolean; /** Enable standalone route-miss 404 handling (from experimental.globalNotFound). */
+  globalNotFound?: boolean; /** Enables Next.js Cache Components semantics for App Router document HTML. */
   cacheComponents?: boolean; /** Whether the RSC build discovered any server references. Defaults to true. */
   hasServerActions?: boolean; /** Internationalization routing config for middleware matcher locale handling. */
   i18n?: NextI18nConfig | null;

package/dist/entries/app-rsc-entry.js

@@ -1,6 +1,7 @@
 import { normalizePathSeparators } from "../utils/path.js";
 import { resolveEntryPath } from "./runtime-entry-module.js";
 import { isProxyFile } from "../server/middleware.js";
+import { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_SIZES } from "../server/image-optimization.js";
 import { buildAppRscManifestCode } from "./app-rsc-manifest.js";
 import { generateDevOriginCheckCode } from "../server/dev-origin-check.js";
 import { randomUUID } from "node:crypto";
@@ -16,7 +17,7 @@ import { randomUUID } from "node:crypto";
 */
 const DEFAULT_EXPIRE_TIME = 31536e3;
 const DEFAULT_REACT_MAX_HEADERS_LENGTH = 6e3;
-const middlewareRequestHeadersPath = resolveEntryPath("../server/middleware-request-headers.js", import.meta.url);
+const middlewareRequestHeadersPath = resolveEntryPath("../utils/middleware-request-headers.js", import.meta.url);
 const normalizePathModulePath = resolveEntryPath("../server/normalize-path.js", import.meta.url);
 const appRouteHandlerDispatchPath = resolveEntryPath("../server/app-route-handler-dispatch.js", import.meta.url);
 const appRouteHandlerResponsePath = resolveEntryPath("../server/app-route-handler-response.js", import.meta.url);
@@ -82,11 +83,19 @@ function generateRscEntry(appDir, routes, middlewarePath, metadataRoutes, global
 	const hasPagesDir = config?.hasPagesDir ?? false;
 	const publicFiles = config?.publicFiles ?? [];
 	const draftModeSecret = config?.draftModeSecret ?? randomUUID();
+	const imageAllowedWidths = [...config?.imageConfig?.deviceSizes ?? DEFAULT_DEVICE_SIZES, ...config?.imageConfig?.imageSizes ?? DEFAULT_IMAGE_SIZES];
+	const imageConfig = {
+		qualities: config?.imageConfig?.qualities,
+		dangerouslyAllowSVG: config?.imageConfig?.dangerouslyAllowSVG,
+		dangerouslyAllowLocalIP: config?.imageConfig?.dangerouslyAllowLocalIP,
+		contentDispositionType: config?.imageConfig?.contentDispositionType,
+		contentSecurityPolicy: config?.imageConfig?.contentSecurityPolicy
+	};
 	const { imports, routeEntries, metaRouteEntries, generateStaticParamsEntries, rootParamNameEntries, rootNotFoundVar, rootForbiddenVar, rootUnauthorizedVar, rootLayoutVars, globalErrorVar, globalNotFoundImportSpecifier } = buildAppRscManifestCode({
 		routes,
 		metadataRoutes,
 		globalErrorPath,
-		globalNotFoundPath: config?.globalNotFoundPath ?? null
+		globalNotFoundPath: config?.globalNotFound === true ? config.globalNotFoundPath ?? null : null
 	});
 	const loadPrerenderPagesRoutesCode = hasPagesDir ? `
 async function __loadPrerenderPagesRoutes() {
@@ -123,6 +132,8 @@ ${instrumentationPath ? `import * as _instrumentation from ${JSON.stringify(norm
 import { ensureInstrumentationRegistered as __ensureInstrumentationRegistered } from ${JSON.stringify(instrumentationRuntimePath)};` : ""}
 import { createAppRscHandler } from "vinext/server/app-rsc-handler";
 import { registerConfiguredCacheAdapters as __registerConfiguredCacheAdapters } from "virtual:vinext-cache-adapters";
+import __pagesClientAssets from "virtual:vinext-pages-client-assets";
+import { setPagesClientAssets as __setPagesClientAssets } from "vinext/server/pages-client-assets";
 import { decodePathParams as __decodePathParams } from ${JSON.stringify(normalizePathModulePath)};
 import { buildRequestHeadersFromMiddlewareResponse as __buildRequestHeadersFromMiddlewareResponse } from ${JSON.stringify(middlewareRequestHeadersPath)};
 ${hasPagesDir ? `import {
@@ -245,6 +256,11 @@ function __resolveRouteFetchCacheMode(route) {
   return __resolveAppPageFetchCacheMode({
     layouts: route.layouts,
     page: route.page,
+    parallelSegments: Object.values(route.slots ?? {}).flatMap((slot) => [
+      slot.layout,
+      ...(slot.configLayouts ?? []),
+      slot.page ?? slot.default,
+    ]),
   });
 }
 
@@ -252,6 +268,11 @@ function __resolveRouteDynamicConfig(route) {
   return __resolveAppPageSegmentConfig({
     layouts: route.layouts,
     page: route.page,
+    parallelSegments: Object.values(route.slots ?? {}).flatMap((slot) => [
+      slot.layout,
+      ...(slot.configLayouts ?? []),
+      slot.page ?? slot.default,
+    ]),
   }).dynamicConfig ?? null;
 }
 
@@ -259,6 +280,11 @@ function __resolveRouteRuntime(route) {
   return __resolveAppPageSegmentConfig({
     layouts: route.layouts,
     page: route.page,
+    parallelSegments: Object.values(route.slots ?? {}).flatMap((slot) => [
+      slot.layout,
+      ...(slot.configLayouts ?? []),
+      slot.page ?? slot.default,
+    ]),
   }).runtime ?? null;
 }
 
@@ -339,6 +365,7 @@ const __fallbackRenderer = __createAppFallbackRenderer({
   },
   globalErrorModule: ${globalErrorVar ? globalErrorVar : "null"},
   loadGlobalNotFoundModule: __loadGlobalNotFoundModule,
+  globalNotFoundEnabled: ${config?.globalNotFound === true},
   metadataRoutes,
   ssrLoader() {
     return import.meta.viteRsc.loadModule("ssr", "index");
@@ -400,7 +427,7 @@ const __i18nConfig = ${JSON.stringify(i18nConfig)};
 const __configRedirects = ${JSON.stringify(redirects)};
 const __configRewrites = ${JSON.stringify(rewrites)};
 const __configHeaders = ${JSON.stringify(headers)};
-const __imageConfig = ${JSON.stringify(config?.imageConfig)};
+const __runtimeImageConfig = ${JSON.stringify(config?.imageConfig)};
 const __publicFiles = new Set(${JSON.stringify(publicFiles)});
 const __allowedOrigins = ${JSON.stringify(allowedOrigins)};
 const __expireTime = ${JSON.stringify(expireTime)};
@@ -411,6 +438,8 @@ const __reactMaxHeadersLength = ${JSON.stringify(reactMaxHeadersLength)};
 // mirrors the embedded \`__basePath\` pattern (and Pages Router's
 // \`vinextConfig\` export). Empty string when unset.
 export const __assetPrefix = ${JSON.stringify(assetPrefix)};
+export const __imageAllowedWidths = ${JSON.stringify(imageAllowedWidths)};
+export const __imageConfig = ${JSON.stringify(imageConfig)};
 export const __inlineCss = ${JSON.stringify(inlineCss)};
 export const __hasPagesDir = ${JSON.stringify(hasPagesDir)};
 export const getRenderedConcreteUrlPathsForRoute = __getRenderedConcreteUrlPathsForRoute;
@@ -459,6 +488,7 @@ const rootParamNamesMap = {
 ${rootParamNameEntries.join("\n")}
 };
 
+__setPagesClientAssets(__pagesClientAssets);
 export default createAppRscHandler({
   basePath: __basePath,
   buildId: process.env.__VINEXT_BUILD_ID ?? null,
@@ -473,7 +503,7 @@ export default createAppRscHandler({
   },` : ""}
   configRedirects: __configRedirects,
   configRewrites: __configRewrites,
-  imageConfig: __imageConfig,
+  imageConfig: __runtimeImageConfig,
   isDev: process.env.NODE_ENV !== "production",
   draftModeSecret: __draftModeSecret,
   dispatchMatchedPage({
@@ -505,13 +535,32 @@ export default createAppRscHandler({
     const PageComponent = route.page?.default;
     const __segmentConfig = __resolveAppPageSegmentConfig({
       layouts: route.layouts,
+      layoutTreePositions: route.layoutTreePositions,
       page: route.page,
-      parallelPages: Object.values(route.slots ?? {}).map((slot) => slot.page),
+      parallelBranches: Object.values(route.slots ?? {}).map((slot) => ({
+        layout: slot.layout,
+        configLayouts: slot.configLayouts,
+        configLayoutTreePositions: slot.configLayoutTreePositions,
+        page: slot.page ?? slot.default,
+        routeSegments: slot.routeSegments,
+      })),
+      parallelPages: Object.values(route.slots ?? {}).map((slot) => slot.page ?? slot.default),
+      routeSegments: route.routeSegments,
     });
     const __generateStaticParams = __resolveAppPageGenerateStaticParamsSources({
       layouts: route.layouts,
       layoutTreePositions: route.layoutTreePositions,
       page: route.page,
+      parallelBranches: Object.values(route.slots ?? {}).map((slot) => ({
+        layout: slot.layout,
+        configLayouts: slot.configLayouts,
+        configLayoutTreePositions: slot.configLayoutTreePositions,
+        page: slot.page ?? slot.default,
+        paramNames: slot.slotParamNames,
+        patternParts: slot.slotPatternParts,
+        routeSegments: slot.routeSegments,
+      })),
+      routePatternParts: route.patternParts,
       routeSegments: route.routeSegments,
     });
     const _asyncRouteParams = makeThenableParams(params);
@@ -520,7 +569,7 @@ export default createAppRscHandler({
       ensureRouteLoaded: __ensureRouteLoaded,
       clientTraceMetadata: __clientTraceMetadata,
       reactMaxHeadersLength: __reactMaxHeadersLength,
-      buildPageElement(targetRoute, targetParams, targetOpts, targetSearchParams, layoutParamAccess) {
+      buildPageElement(targetRoute, targetParams, targetOpts, targetSearchParams, layoutParamAccess, buildOptions) {
         return buildPageElements(targetRoute, targetParams, cleanPathname, {
           opts: targetOpts,
           searchParams: targetSearchParams,
@@ -528,6 +577,8 @@ export default createAppRscHandler({
           request,
           mountedSlotsHeader,
           renderMode,
+          observeMetadataSearchParamsAccess: buildOptions?.observeMetadataSearchParamsAccess === true,
+          observePageSearchParamsAccess: buildOptions?.observePageSearchParamsAccess === true,
         }, layoutParamAccess, displayPathname);
       },
       clientReuseManifest,
@@ -598,7 +649,7 @@ export default createAppRscHandler({
           route,
         });
       },
-      async probePage() {
+      async probePage(probeSearchParams = searchParams) {
         const __probeIntercept = findIntercept(cleanPathname, interceptionContext);
         // The intercepting-route page module is lazy (page: null + __pageLoader).
         // Resolve it before probing so buildAppPageProbes inspects the real page
@@ -613,21 +664,21 @@ export default createAppRscHandler({
           route,
           pageComponent: PageComponent,
           asyncRouteParams: _asyncRouteParams,
-          searchParams,
+          searchParams: probeSearchParams,
           intercept: __probeIntercept,
           isRscRequest,
           matchedParams: params,
           makeThenableParams,
         }));
       },
-      renderErrorBoundaryPage(renderErr) {
+      renderErrorBoundaryPage(renderErr, errorOrigin) {
         const __activeIntercept = findIntercept(cleanPathname, interceptionContext);
         return __fallbackRenderer.renderErrorBoundary(route, renderErr, isRscRequest, request, params, scriptNonce, middlewareContext, {
           isEdgeRuntime: __isEdgeRuntime(__segmentConfig.runtime),
           sourcePageSegments: __activeIntercept?.slotKey === __SIBLING_PAGE_INTERCEPT_SLOT_KEY
             ? __activeIntercept.sourcePageSegments
             : null,
-        });
+        }, errorOrigin);
       },
       renderHttpAccessFallbackPage(statusCode, opts, currentMiddlewareContext) {
         const __activeIntercept = findIntercept(cleanPathname, interceptionContext);
@@ -777,7 +828,7 @@ export default createAppRscHandler({
     const __actionMatch = matchRoute(cleanPathname);
     if (__actionMatch) await __ensureRouteLoaded(__actionMatch.route);
     const __actionIsEdgeRuntime = __actionMatch
-      ? __isEdgeRuntime(__resolveAppPageSegmentConfig({ layouts: __actionMatch.route.layouts, page: __actionMatch.route.page }).runtime)
+      ? __isEdgeRuntime(__resolveRouteRuntime(__actionMatch.route))
       : false;
     return __handleServerActionRscRequest({
       actionId,
@@ -795,6 +846,8 @@ export default createAppRscHandler({
         request: actionRequest,
         mountedSlotsHeader: actionMountedSlotsHeader,
         renderMode: actionRenderMode,
+        observeMetadataSearchParamsAccess,
+        observePageSearchParamsAccess,
       }) {
         return buildPageElements(actionRoute, actionParams, actionCleanPathname, {
           opts: interceptOpts,
@@ -803,6 +856,8 @@ export default createAppRscHandler({
           request: actionRequest,
           mountedSlotsHeader: actionMountedSlotsHeader,
           renderMode: actionRenderMode,
+          observeMetadataSearchParamsAccess: observeMetadataSearchParamsAccess === true,
+          observePageSearchParamsAccess: observePageSearchParamsAccess === true,
         });
       },
       cleanPathname,
@@ -828,6 +883,7 @@ export default createAppRscHandler({
       },
       createTemporaryReferenceSet,
       decodeReply,
+      draftModeSecret: __draftModeSecret,
       findIntercept(pathnameToMatch) {
         return findIntercept(pathnameToMatch, interceptionContext);
       },
@@ -871,6 +927,8 @@ export default createAppRscHandler({
         return {
           interceptionContext,
           interceptLayouts: intercept.interceptLayouts,
+          interceptLayoutSegments: intercept.interceptLayoutSegments,
+          interceptBranchSegments: intercept.interceptBranchSegments,
           interceptSlotId: intercept.slotId,
           interceptSlotKey: intercept.slotKey,
           interceptSourceMatchedUrl: interceptionContext,
@@ -910,7 +968,7 @@ export default createAppRscHandler({
   },` : ""}
   publicFiles: __publicFiles,
   renderNotFound({ isRscRequest, matchedParams, middlewareContext, request, route, scriptNonce }) {
-    const __isEdge = route ? __isEdgeRuntime(__resolveAppPageSegmentConfig({ layouts: route.layouts, page: route.page }).runtime) : false;
+    const __isEdge = route ? __isEdgeRuntime(__resolveRouteRuntime(route)) : false;
     return __fallbackRenderer.renderNotFound(route, isRscRequest, request, matchedParams, scriptNonce, middlewareContext, { isEdgeRuntime: __isEdge });
   },
   ${hasPagesDir ? `async renderPagesFallback({ allowRscDocumentFallback, appRouteMatch, isDataRequest, isRscRequest, matchKind, middlewareContext, pathname, pagesDataRequest, request, url }) {

package/dist/entries/app-rsc-manifest.js

@@ -74,6 +74,7 @@ function registerRouteModules(routes, imports) {
 			if (slot.pagePath) imports.getLazyLoaderVar(slot.pagePath);
 			if (slot.defaultPath) imports.getLazyLoaderVar(slot.defaultPath);
 			if (slot.layoutPath) imports.getLazyLoaderVar(slot.layoutPath);
+			for (const layoutPath of slot.configLayoutPaths ?? []) imports.getLazyLoaderVar(layoutPath);
 			if (slot.loadingPath) imports.getLazyLoaderVar(slot.loadingPath);
 			if (slot.errorPath) imports.getLazyLoaderVar(slot.errorPath);
 			for (const ir of slot.interceptingRoutes) {
@@ -112,6 +113,8 @@ function buildRouteEntries(routes, imports) {
       slotId: ${JSON.stringify(ir.slotId ?? null)},
       interceptLayouts: ${moduleArray(ir.layoutPaths.length)},
       __loadInterceptLayouts: ${lazyLoaderArray(ir.layoutPaths, imports)},
+      interceptLayoutSegments: ${JSON.stringify(ir.layoutSegments ?? [])},
+      interceptBranchSegments: ${JSON.stringify(ir.branchSegments ?? [])},
       page: null,
       __pageLoader: ${imports.getLazyLoaderVar(ir.pagePath)},
       params: ${JSON.stringify(ir.params)},
@@ -124,6 +127,8 @@ function buildRouteEntries(routes, imports) {
           sourcePageSegments: ${JSON.stringify(ir.sourcePageSegments)},
           interceptLayouts: ${moduleArray(ir.layoutPaths.length)},
           __loadInterceptLayouts: ${lazyLoaderArray(ir.layoutPaths, imports)},
+          interceptLayoutSegments: ${JSON.stringify(ir.layoutSegments ?? [])},
+          interceptBranchSegments: ${JSON.stringify(ir.branchSegments ?? [])},
           page: null,
           __pageLoader: ${imports.getLazyLoaderVar(ir.pagePath)},
           params: ${JSON.stringify(ir.params)},
@@ -137,6 +142,9 @@ function buildRouteEntries(routes, imports) {
         __loadDefault: ${slot.defaultPath ? imports.getLazyLoaderVar(slot.defaultPath) : "null"},
         layout: null,
         __loadLayout: ${slot.layoutPath ? imports.getLazyLoaderVar(slot.layoutPath) : "null"},
+        configLayouts: ${moduleArray(slot.configLayoutPaths?.length ?? 0)},
+        __loadConfigLayouts: ${lazyLoaderArray(slot.configLayoutPaths ?? [], imports)},
+        configLayoutTreePositions: ${JSON.stringify(slot.configLayoutTreePositions ?? [])},
         loading: null,
         __loadLoading: ${slot.loadingPath ? imports.getLazyLoaderVar(slot.loadingPath) : "null"},
         error: null,

package/dist/entries/pages-client-entry.d.ts

@@ -6,6 +6,7 @@ import { VinextLinkPrefetchRoute } from "../client/vinext-next-data.js";
 declare function generateClientEntry(pagesDir: string, nextConfig: ResolvedNextConfig, fileMatcher: ReturnType<typeof createValidFileMatcher>, options?: {
   appPrefetchRoutes?: readonly VinextLinkPrefetchRoute[];
   instrumentationClientPath?: string | null;
+  reactPreamble?: boolean;
 }): Promise<string>;
 //#endregion
 export { generateClientEntry };

package/dist/entries/pages-client-entry.js

@@ -2,6 +2,7 @@ import { normalizePathSeparators } from "../utils/path.js";
 import { findFileWithExts } from "../routing/file-matcher.js";
 import { patternToNextFormat } from "../routing/route-validation.js";
 import { apiRouter, pagesRouter } from "../routing/pages-router.js";
+import "./pages-entry-helpers.js";
 //#region src/entries/pages-client-entry.ts
 /**
 * Pages Router client hydration entry generator.
@@ -46,7 +47,7 @@ async function generateClientEntry(pagesDir, nextConfig, fileMatcher, options =
 		return `  ${JSON.stringify(nextFormatPattern)}: () => import(${JSON.stringify(absPath)})`;
 	});
 	const appFileBase = appFilePath ? normalizePathSeparators(appFilePath) : void 0;
-	return `${instrumentationClientPath ? `import ${JSON.stringify(normalizePathSeparators(instrumentationClientPath))};\n` : ""}
+	return `${instrumentationClientPath ? `import ${JSON.stringify(normalizePathSeparators(instrumentationClientPath))};\n` : ""}${options.reactPreamble === false ? "" : "import \"@vitejs/plugin-react/preamble\";\n"}
 import "vinext/instrumentation-client";
 import React from "react";
 import { hydrateRoot } from "react-dom/client";

package/dist/entries/pages-server-entry.js

@@ -3,6 +3,7 @@ import { findFileWithExts } from "../routing/file-matcher.js";
 import { apiRouter, pagesRouter } from "../routing/pages-router.js";
 import { resolveEntryPath } from "./runtime-entry-module.js";
 import { isProxyFile } from "../server/middleware.js";
+import "./pages-entry-helpers.js";
 //#region src/entries/pages-server-entry.ts
 /**
 * Pages Router server entry generator.
@@ -127,6 +128,8 @@ import Router, { setSSRContext, wrapWithRouterContext, getPagesNavigationIsReady
 import { _runWithCacheState } from "vinext/shims/cache-request-state";
 import { configureMemoryCacheHandler as __configureMemoryCacheHandler } from "vinext/shims/cache-handler";
 import { registerConfiguredCacheAdapters as __registerConfiguredCacheAdapters } from "virtual:vinext-cache-adapters";
+import __pagesClientAssets from "virtual:vinext-pages-client-assets";
+import { setPagesClientAssets as __setPagesClientAssets } from "vinext/server/pages-client-assets";
 import { runWithPrivateCache } from "vinext/cache-runtime";
 import { ensureFetchPatch, runWithFetchCache } from "vinext/fetch-cache";
 import "vinext/router-state";
@@ -163,7 +166,7 @@ export const buildId = ${buildIdJson};
 export function normalizeDataRequest(request) {
   return __normalizePagesDataRequest(request, buildId);
 }
-const __hasMiddleware = ${JSON.stringify(Boolean(middlewarePath))};
+export const hasMiddleware = ${JSON.stringify(Boolean(middlewarePath))};
 
 // Full resolved config for production server (embedded at build time)
 export const vinextConfig = ${vinextConfigJson};
@@ -270,6 +273,7 @@ export function matchApiRoute(url, request) {
 // All next/*-derived values are passed as closures so the handler module
 // stays importable in test environments (the root vite.config.ts only
 // aliases vinext/shims/*, not next/*).
+__setPagesClientAssets(__pagesClientAssets);
 const _renderPage = __createPagesPageHandler({
   pageRoutes,
   errorPageRoute: _errorPageRoute,
@@ -285,7 +289,7 @@ const _renderPage = __createPagesPageHandler({
     disableOptimizedLoading: vinextConfig.disableOptimizedLoading,
   },
   buildId,
-  hasMiddleware: __hasMiddleware,
+  hasMiddleware,
   appAssetPath: _appAssetPath,
   hasRewrites:
     vinextConfig.rewrites.beforeFiles.length > 0 ||

package/dist/image/image-adapters-virtual.d.ts

@@ -0,0 +1,59 @@
+//#region src/image/image-adapters-virtual.d.ts
+/**
+ * Code generation for the `virtual:vinext-image-adapters` module, resolved by
+ * the vinext vite plugin from the user's `images` config ({@link VinextImageConfig}).
+ *
+ * The generated module exports `registerConfiguredImageOptimizer(env)`, which the
+ * server entries call on each request. It self-guards (the optimizer instantiates
+ * once per isolate) and is a no-op when nothing is configured. Registration is
+ * resilient: a factory that throws (e.g. a Cloudflare Images adapter on the
+ * Node.js server, where the `IMAGES` binding can't exist) is logged and skipped
+ * rather than failing every request, so the same config can be registered from
+ * every runtime/router entry. When no optimizer is registered, image requests
+ * fall back to serving the original asset unoptimized.
+ *
+ * Descriptor `options` are inlined into the generated module and forwarded to the
+ * factory at runtime, so a config-time builder like `imagesOptimizer({ binding })`
+ * never touches the Workers runtime — instantiation is deferred to the first
+ * request.
+ *
+ * This mirrors the cache-adapter pattern in `cache/cache-adapters-virtual.ts`.
+ */
+/**
+ * A serializable pointer to an image optimizer adapter module — the shape of the
+ * `images.optimizer` slot in the vinext() plugin config. Produced by an adapter
+ * builder (e.g. `imagesOptimizer(...)` from `@vinext/cloudflare/images/images-optimizer`)
+ * or written by hand. `options` must be JSON-serializable: it is inlined into the
+ * generated registration module and forwarded to the adapter factory at runtime.
+ */
+type ImageAdapterDescriptor<O extends Record<string, unknown> = Record<string, unknown>> = {
+  /**
+   * Module specifier (or absolute path, e.g. from `require.resolve(...)`) whose
+   * default export is an image optimizer factory.
+   */
+  adapter: string; /** JSON-serializable options forwarded to the factory at runtime. */
+  options?: O;
+};
+/**
+ * The `images` option of the vinext() plugin: declaratively register the
+ * server-side image optimizer (transform backend) instead of wiring `env.IMAGES`
+ * into a custom worker entry.
+ *
+ * This is complementary to the `images` field in `next.config.js`, which
+ * configures the standard Next.js image options (`remotePatterns`, `deviceSizes`,
+ * `dangerouslyAllowSVG`, etc.). Those continue to be read from next.config; this
+ * option only selects the runtime transform backend, which can't be expressed as
+ * serializable next.config data.
+ */
+type VinextImageConfig = {
+  /** Server-side image optimizer adapter (the `/_next/image` transform backend). */optimizer?: ImageAdapterDescriptor;
+};
+/** Public virtual module id imported by the server entries. */
+declare const VIRTUAL_IMAGE_ADAPTERS = "virtual:vinext-image-adapters";
+/**
+ * Generate the source of the `virtual:vinext-image-adapters` module for the
+ * given config. Always exports `registerConfiguredImageOptimizer(env)`.
+ */
+declare function generateImageAdaptersModule(images?: VinextImageConfig): string;
+//#endregion
+export { VIRTUAL_IMAGE_ADAPTERS, VinextImageConfig, generateImageAdaptersModule };

package/dist/image/image-adapters-virtual.js

@@ -0,0 +1,50 @@
+//#region src/image/image-adapters-virtual.ts
+/** Public virtual module id imported by the server entries. */
+const VIRTUAL_IMAGE_ADAPTERS = "virtual:vinext-image-adapters";
+/**
+* Serialize descriptor options into a JS expression for inlining. Plain JSON is
+* a valid JS literal; `undefined` when there are no options. Throws a clear
+* config-time error (not a runtime one) if options are not serializable.
+*/
+function inlineOptions(adapter, options) {
+	if (options === void 0) return "undefined";
+	try {
+		return JSON.stringify(options);
+	} catch (cause) {
+		throw new Error(`[vinext] image adapter "${adapter}" options must be JSON-serializable.`, { cause });
+	}
+}
+/**
+* Generate the source of the `virtual:vinext-image-adapters` module for the
+* given config. Always exports `registerConfiguredImageOptimizer(env)`.
+*/
+function generateImageAdaptersModule(images) {
+	const optimizer = images?.optimizer;
+	if (!optimizer?.adapter) return [
+		"// vinext: no images.optimizer adapter configured — registration is a no-op.",
+		"export function registerConfiguredImageOptimizer() {}",
+		""
+	].join("\n");
+	return [
+		"// vinext: generated from the `images` option in your vinext() plugin config.",
+		`import __vinextImageOptimizerFactory from ${JSON.stringify(optimizer.adapter)};`,
+		`import { setImageOptimizer } from "vinext/server/image-optimization";`,
+		"",
+		"// A factory that throws (e.g. a missing binding on an incompatible runtime)",
+		"// is logged and skipped so images fall back to unoptimized passthrough.",
+		"let __vinextImageOptimizerRegistered = false;",
+		"",
+		"export function registerConfiguredImageOptimizer(env) {",
+		"  if (__vinextImageOptimizerRegistered) return;",
+		"  __vinextImageOptimizerRegistered = true;",
+		"  try {",
+		`    setImageOptimizer(__vinextImageOptimizerFactory({ env, options: ${inlineOptions(optimizer.adapter, optimizer.options)} }));`,
+		"  } catch (error) {",
+		"    console.warn(\"[vinext] failed to initialize the configured image optimizer; serving images unoptimized.\", error);",
+		"  }",
+		"}",
+		""
+	].join("\n");
+}
+//#endregion
+export { VIRTUAL_IMAGE_ADAPTERS, generateImageAdaptersModule };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { NextConfig, NextConfigInput } from "./config/next-config.js";
 import { AppStaticExportOptions, StaticExportOptions, StaticExportResult, staticExportApp, staticExportPages } from "./build/static-export.js";
 import { VinextCacheConfig } from "./cache/cache-adapters-virtual.js";
+import { VinextImageConfig } from "./image/image-adapters-virtual.js";
 import { PluginOption } from "vite";
 import { Options } from "@vitejs/plugin-react";
 
@@ -97,6 +98,17 @@ type VinextOptions = {
    * })
    */
   cache?: VinextCacheConfig;
+  /**
+   * Configure the server-side image optimizer declaratively. The adapter factory
+   * receives the host `env`, allowing bindings such as Cloudflare Images to be
+   * used by both built-in and custom worker entrypoints that forward `env`.
+   *
+   * @example
+   * import { imagesOptimizer } from "@vinext/cloudflare/images/images-optimizer";
+   *
+   * vinext({ images: { optimizer: imagesOptimizer() } })
+   */
+  images?: VinextImageConfig;
   /**
    * Experimental vinext-only feature flags.
    */