feat(image): support images.loaderFile and emit srcSet from custom loaders

packages/vinext/src/check.ts

@@ -186,7 +186,7 @@ const CONFIG_SUPPORT: Record<string, { status: Status; detail?: string }> = {
   images: {
     status: "partial",
     detail:
-      "remotePatterns validated; on-the-fly optimization via images.optimizer (Cloudflare Images), passthrough otherwise",
+      "remotePatterns validated; loader/loaderFile supported; on-the-fly optimization via images.optimizer (Cloudflare Images), passthrough otherwise",
   },
   allowedDevOrigins: { status: "supported", detail: "dev server cross-origin allowlist" },
   output: {

packages/vinext/src/config/next-config.ts

@@ -230,6 +230,20 @@ export type NextConfig = {
     dangerouslyAllowSVG?: boolean;
     /** Allow image optimization for hostnames that resolve to private IP addresses. This is a security risk (SSRF) — only enable for private networks when you understand the risk. */
     dangerouslyAllowLocalIP?: boolean;
+    /**
+     * Which image loader generates image URLs. Only "default" (the built-in
+     * `/_next/image` endpoint) and "custom" (paired with `loaderFile`) are
+     * implemented — the named CDN loaders exist only in `next/legacy/image`
+     * upstream and are rejected here rather than silently ignored.
+     */
+    loader?: "default" | "custom";
+    /**
+     * Path to a file whose default export is an image loader function
+     * `({ src, width, quality }) => string`. Resolved relative to the project
+     * root. When set, it replaces the built-in `/_next/image` loader for every
+     * image that does not pass its own `loader` prop.
+     */
+    loaderFile?: string;
     /** Content-Disposition header for image responses. Defaults to "inline". */
     contentDispositionType?: "inline" | "attachment";
     /** Content-Security-Policy header for image responses. Defaults to "script-src 'none'; frame-src 'none'; sandbox;" */
@@ -1222,6 +1236,53 @@ export function createRscCompatibilityId(
   return randomUUID();
 }
 
+/**
+ * Validate `images.loader` and resolve `images.loaderFile` to an absolute path,
+ * mirroring Next.js's checks in `server/config.ts`.
+ *
+ * Failing at config time is deliberate: a mistyped path that silently fell back
+ * to the built-in loader is indistinguishable from `loaderFile` not being
+ * supported at all, which is the exact failure mode this plumbing exists to fix.
+ *
+ * `loader: "custom"` without a `loaderFile` is intentionally NOT an error —
+ * upstream allows it, and defers to a per-image `loader` prop. The shim reports
+ * that case at render time instead.
+ */
+function resolveImageLoaderFile(
+  images: NonNullable<NextConfig["images"]>,
+  root: string,
+): string | undefined {
+  const loaderFile =
+    typeof images.loaderFile === "string" && images.loaderFile !== ""
+      ? images.loaderFile
+      : undefined;
+
+  // Widened deliberately: next.config is user-authored JavaScript, so the
+  // declared union is a hint, not a guarantee. A `loader: "imgix"` left over
+  // from a Next.js project must be reported rather than silently accepted.
+  //
+  // Checked before `loaderFile` is required, because a named loader on its own
+  // is the more dangerous case: nothing downstream would reject it, so every
+  // image would quietly be served from `/_next/image` instead of the CDN the
+  // config names.
+  const loader: string | undefined = images.loader;
+  if (loader !== undefined && loader !== "default" && loader !== "custom") {
+    throw new Error(
+      loaderFile
+        ? `Specified images.loader property (${loader}) cannot be used with images.loaderFile property. Please set images.loader to "custom".`
+        : `Specified images.loader property (${loader}) is not supported. The named CDN loaders exist only in next/legacy/image; set images.loader to "custom" and point images.loaderFile at a loader module instead.`,
+    );
+  }
+
+  if (!loaderFile) return undefined;
+
+  const absolutePath = toSlash(path.resolve(root, loaderFile));
+  if (!fs.existsSync(absolutePath)) {
+    throw new Error(`Specified images.loaderFile does not exist at "${absolutePath}".`);
+  }
+  return absolutePath;
+}
+
 /**
  * Converts a cache handler path to a filesystem path.
  * ESM's import.meta.resolve() returns file:// URLs which break when concatenated
@@ -1876,6 +1937,7 @@ export async function resolveNextConfig(
   const images = config.images
     ? {
         ...config.images,
+        loaderFile: resolveImageLoaderFile(config.images, root),
         remotePatterns: config.images.remotePatterns?.map((pattern) =>
           pattern instanceof URL
             ? {

packages/vinext/src/image/image-loader-unconfigured.ts

@@ -0,0 +1,13 @@
+/**
+ * Stand-in for the generated `virtual:vinext-image-loader` module.
+ *
+ * Tests import the `next/image` shim directly, without the vinext vite plugin,
+ * so the virtual module has no resolver. This file is aliased in place of it
+ * (see `WORKSPACE_SRC_ALIAS` in vite.config.ts) and mirrors what the generator
+ * emits when `images.loaderFile` is not configured.
+ *
+ * Tests that need a configured loader should assert on
+ * `generateImageLoaderModule()` output rather than trying to swap this module.
+ */
+export default undefined;
+export const requiresLoaderProp = false;

packages/vinext/src/image/image-loader-virtual.ts

@@ -0,0 +1,94 @@
+/**
+ * Code generation for the `virtual:vinext-image-loader` module, resolved by the
+ * vinext vite plugin from `images.loaderFile` in next.config.
+ *
+ * Next.js implements `loaderFile` as a bundler alias: the module that
+ * `next/image` imports for its default loader
+ * (`next/dist/shared/lib/image-loader`) is swapped for the user's file — see
+ * `create-compiler-aliases.ts` upstream. vinext replaces `next/image` wholesale
+ * with its own shim, so there is no upstream module left to alias. Instead the
+ * shim imports this virtual module unconditionally and the plugin generates
+ * either a re-export of the user's loader or an inert stub.
+ *
+ * Every branch emits the same two exports so the shim's unconditional import
+ * stays valid whether or not `loaderFile` is configured: `default` is the loader
+ * (or `undefined`), and `requiresLoaderProp` says whether the configuration
+ * demands that each `<Image>` bring its own `loader` prop.
+ *
+ * This mirrors the adapter pattern in `image/image-adapters-virtual.ts`.
+ */
+
+/** Public virtual module id imported by the `next/image` shim. */
+export const VIRTUAL_IMAGE_LOADER = "virtual:vinext-image-loader";
+
+/**
+ * Next.js's error for a `loaderFile` whose module has no default export.
+ * Kept verbatim so existing troubleshooting docs and searches still apply.
+ */
+const MISSING_DEFAULT_EXPORT_ERROR =
+  "images.loaderFile detected but the file is missing default export.\n" +
+  "Read more: https://nextjs.org/docs/messages/invalid-images-config";
+
+/**
+ * Generate the source of the `virtual:vinext-image-loader` module.
+ *
+ * @param images The resolved `images` block from next.config. `loaderFile` is
+ *   expected to already be an absolute path (see `resolveImageLoaderFile`).
+ */
+export function generateImageLoaderModule(images?: {
+  loader?: "default" | "custom";
+  loaderFile?: string;
+}): string {
+  const loaderFile = images?.loaderFile;
+
+  // `loader: "custom"` with no `loaderFile` means every image must supply its
+  // own `loader` prop. Export a loader that reports the omission instead of
+  // silently falling back to `/_next/image`, matching upstream's `customLoader`.
+  if (!loaderFile && images?.loader === "custom") {
+    return [
+      '// vinext: images.loader is "custom" with no images.loaderFile — each',
+      "// <Image> must pass its own `loader` prop.",
+      "export default function customImageLoader({ src }) {",
+      "  throw new Error(",
+      "    'Image with src \"' + src + '\" is missing \"loader\" prop.\\n' +",
+      "      'Read more: https://nextjs.org/docs/messages/next-image-missing-loader',",
+      "  );",
+      "}",
+      "",
+      "// Tells the shim the default export reports a misconfiguration rather than",
+      "// generating URLs — see image/image-loader-virtual.ts.",
+      "export const requiresLoaderProp = true;",
+      "",
+    ].join("\n");
+  }
+
+  // Nothing configured → the shim falls back to its built-in `/_next/image`
+  // loader. `undefined` (not `null`) so the shim's `??` fallback reads naturally.
+  if (!loaderFile) {
+    return [
+      "// vinext: no images.loaderFile configured — the built-in /_next/image loader is used.",
+      "export default undefined;",
+      "export const requiresLoaderProp = false;",
+      "",
+    ].join("\n");
+  }
+
+  return [
+    "// vinext: generated from `images.loaderFile` in your next.config.",
+    `import * as __vinextUserImageLoaderModule from ${JSON.stringify(loaderFile)};`,
+    "",
+    "const __vinextImageLoader = __vinextUserImageLoaderModule.default;",
+    "",
+    "// Configuring loaderFile is an explicit opt-in, so a module that cannot",
+    "// supply a loader is a config error worth failing on immediately rather",
+    "// than silently falling back to the built-in optimizer — which would be",
+    "// indistinguishable from the loaderFile being ignored.",
+    "if (typeof __vinextImageLoader !== 'function') {",
+    `  throw new Error(${JSON.stringify(MISSING_DEFAULT_EXPORT_ERROR)});`,
+    "}",
+    "",
+    "export default __vinextImageLoader;",
+    "export const requiresLoaderProp = false;",
+    "",
+  ].join("\n");
+}

packages/vinext/src/index.ts

@@ -58,6 +58,7 @@ import {
   generateImageAdaptersModule,
   type VinextImageConfig,
 } from "./image/image-adapters-virtual.js";
+import { VIRTUAL_IMAGE_LOADER, generateImageLoaderModule } from "./image/image-loader-virtual.js";
 import { generateBrowserEntry, toLinkPrefetchRoutes } from "./entries/app-browser-entry.js";
 import {
   collectRouteClassificationManifest,
@@ -1112,6 +1113,8 @@ const RESOLVED_ROOT_PARAMS = VIRTUAL_PREFIX + VIRTUAL_ROOT_PARAMS;
 const RESOLVED_CACHE_ADAPTERS = VIRTUAL_PREFIX + VIRTUAL_CACHE_ADAPTERS;
 /** Virtual module that registers the config-driven image optimizer (see VinextOptions.images). */
 const RESOLVED_IMAGE_ADAPTERS = VIRTUAL_PREFIX + VIRTUAL_IMAGE_ADAPTERS;
+/** Virtual module exposing `images.loaderFile` to the next/image shim. */
+const RESOLVED_IMAGE_LOADER = VIRTUAL_PREFIX + VIRTUAL_IMAGE_LOADER;
 /** Virtual module for composed instrumentation-client bootstrap. */
 const VIRTUAL_INSTRUMENTATION_CLIENT = "private-next-instrumentation-client";
 const RESOLVED_INSTRUMENTATION_CLIENT = `${VIRTUAL_PREFIX}${VIRTUAL_INSTRUMENTATION_CLIENT}.mjs`;
@@ -3663,6 +3666,9 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
           ) {
             return RESOLVED_IMAGE_ADAPTERS;
           }
+          if (cleanId === VIRTUAL_IMAGE_LOADER || cleanId.endsWith("/" + VIRTUAL_IMAGE_LOADER)) {
+            return RESOLVED_IMAGE_LOADER;
+          }
           if (cleanId.startsWith(VIRTUAL_GOOGLE_FONTS + "?")) {
             return RESOLVED_VIRTUAL_GOOGLE_FONTS + cleanId.slice(VIRTUAL_GOOGLE_FONTS.length);
           }
@@ -3836,6 +3842,12 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
           if (id === RESOLVED_IMAGE_ADAPTERS) {
             return generateImageAdaptersModule(options.images);
           }
+          if (id === RESOLVED_IMAGE_LOADER) {
+            // From next.config's `images`, not the vinext() plugin `images`
+            // option — `loaderFile` is a Next.js config key, and the path was
+            // already resolved and existence-checked by resolveNextConfig().
+            return generateImageLoaderModule(nextConfig?.images);
+          }
           if (id === RESOLVED_APP_SSR_ENTRY && hasAppDir) {
             return generateSsrEntry(hasPagesDir);
           }