@doswiftly/storefront-sdk 22.5.1 → 22.7.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 22.7.0
+
+### Minor Changes
+
+- 1bbf3e0: `<Image>` now optimizes images imported in code (`import hero from './hero.webp'`), not just `public/` ones. Such imports are bundled under `/_next/static/media/` and were previously served at full size — one large file for every `srcset` width. The loader now routes them through the image CDN, so they are resized per breakpoint and format-negotiated, typically a 90%+ byte reduction on large gallery/hero images. No code change is required: existing `import` + `<Image>` usage is optimized automatically on the next deploy. A dev-only console hint additionally flags `<Image>` sources that still bypass the CDN (for example external URLs).
+
+## 22.6.0
+
+### Minor Changes
+
+- b1e622d: Add a zero-config Next.js image loader. Re-export `createImageLoader()` from the new
+  `@doswiftly/storefront-sdk/next` entry in your `images.loaderFile` and every `<Image>`
+  is routed through the image CDN: product images get a real responsive `srcset` (a width
+  per entry, so you can drop `transform: { maxWidth }`) and local `public/` images are
+  resized and format-negotiated (AVIF/WebP) instead of shipped at full size. Build assets,
+  external / protocol-relative URLs and `data:` URIs pass through untouched, and
+  `<Image quality>` is a no-op (quality is applied server-side; the format is auto-negotiated). The pure
+  `buildImageLoaderUrl` helper is also exported from the package root for non-`<Image>` use.
+
+  Usage:
+
+  ```ts
+  // lib/image-loader.ts
+  import { createImageLoader } from "@doswiftly/storefront-sdk/next";
+  export default createImageLoader();
+  ```
+
+  ```ts
+  // next.config.ts — bound the generated widths for fewer transforms / better cache hits
+  export default {
+    images: {
+      loader: "custom",
+      loaderFile: "./lib/image-loader.ts",
+      deviceSizes: [640, 750, 828, 1080, 1200, 1920],
+      imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
+    },
+  };
+  ```
+
+  Migration:
+  - New install — nothing to do; existing `<Image>` usage keeps working.
+  - Optional — drop `transform: { maxWidth }` from product-image queries; the loader now sets the width per `srcset` entry.
+
+### Patch Changes
+
+- 91c3b25: Ship TypeScript types for the codegen recipe (`@doswiftly/storefront-operations/codegen`). A `codegen.ts` that imports `createCodegenConfig` now type-checks under `strict` mode, so `next build` no longer fails with a missing-declaration (implicit `any`) error on the recipe import.
+
 ## 22.5.1
 
 ### Patch Changes

package/README.md

@@ -229,6 +229,7 @@ retried.
 | `@doswiftly/storefront-sdk` | Core: transport, middleware, clients, recovery, errors, format, enums, cookie contracts | **0** |
 | `@doswiftly/storefront-sdk/react` | Providers, hooks, stores, pre-built UI components | react, zustand |
 | `@doswiftly/storefront-sdk/react/server` | Server client factory, SDK-BFF auth route, cookie readers | react (peer; `getInitialAuth` additionally requires Next.js) |
+| `@doswiftly/storefront-sdk/next` | Zero-config Next.js adapters — `createImageLoader()` for `images.loaderFile` | **0** |
 | `@doswiftly/storefront-sdk/cache` | Cache strategy functions | **0** |
 
 ## Authentication
@@ -735,6 +736,58 @@ import { Money, PriceDisplay, CartCount } from '@doswiftly/storefront-sdk/react'
 <CartCount count={3} label="items" />
 ```
 
+## Images — zero-config `next/image` loader
+
+`createImageLoader()` is a drop-in loader for Next.js `images.loaderFile`. It
+routes every `<Image>` through the image CDN so each one is resized to the
+viewport (real responsive `srcset`) and format-negotiated (AVIF/WebP from the
+browser `Accept` header) — no per-image configuration.
+
+Create the loader file (zero arguments):
+
+```ts
+// lib/image-loader.ts
+import { createImageLoader } from '@doswiftly/storefront-sdk/next';
+
+export default createImageLoader();
+```
+
+Point Next.js at it, and bound the generated sizes so a fixed set of widths is
+produced (fewer transforms, better cache hit rate):
+
+```ts
+// next.config.ts
+const nextConfig = {
+  images: {
+    loader: 'custom',
+    loaderFile: './lib/image-loader.ts',
+    deviceSizes: [640, 750, 828, 1080, 1200, 1920],
+    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
+  },
+};
+export default nextConfig;
+```
+
+The loader is global and handles each `<Image src>` by category:
+
+| `src` | Handling |
+|-------|----------|
+| Product image (CDN URL from the GraphQL API) | Width set per `srcset` entry — drop `transform: { maxWidth }`, the loader owns the width |
+| Local `public/` image (e.g. `/hero.webp`) | Routed through the CDN, resized + format-negotiated |
+| Image imported in code (`import hero from './hero.webp'`) | Routed through the CDN — the framework bundles it under `/_next/static/media/`, the loader resizes it per `srcset` (no code change needed) |
+| Other build asset (`/_next/*` JS/CSS, `/_nuxt/`, `/_astro/`, `/_app/`), absolute external URL, `data:` URI, SVG | Returned unchanged |
+
+The loader reads `NEXT_PUBLIC_SHOP_ID`, `NEXT_PUBLIC_DEPLOYMENT_COMMIT`, and
+`NEXT_PUBLIC_IMGPROXY_BASE` — all injected by the platform at build/deploy time. When
+they are absent (e.g. local `doswiftly dev`, where `public/` images are served by the
+dev server) the loader leaves local `public/` images untouched; product images, being
+absolute CDN URLs, are unaffected. `<Image quality>` is a no-op — quality is applied
+server-side (the format is still auto-negotiated AVIF/WebP). Pass explicit overrides only for non-standard setups:
+`createImageLoader({ shopId, version, cdnBase })`.
+
+For non-`<Image>` usage (CSS backgrounds, raw `<img>`), build CDN URLs yourself
+with the pure helper `buildImageLoaderUrl` from `@doswiftly/storefront-sdk`.
+
 ## Middleware pipeline
 
 Default order (wired automatically by `StorefrontProvider`):

package/dist/core/image.d.ts

@@ -1,11 +1,19 @@
 /**
  * Image types and utilities for DoSwiftly storefronts.
  *
- * GraphQL API returns ready-to-use CDN URLs with transform query params.
- * No client-side loader needed — use `url(transform: { maxWidth: 800 })` in queries.
+ * Two ways images reach the browser:
+ *  - **Product images**: the GraphQL API returns ready-to-use CDN URLs (you may
+ *    request a size with `url(transform: { maxWidth: 800 })`, but with the image
+ *    loader below the size is no longer needed — the loader sets it per srcset entry).
+ *  - **Local images** (your `public/` folder, e.g. a hero or logo used with the
+ *    Next.js `<Image>` component): routed through the image CDN by the loader so they
+ *    are resized + format-negotiated instead of shipped at full size.
  *
- * imgproxy auto-negotiates AVIF/WEBP from browser Accept header (IMGPROXY_AUTO_AVIF=true).
- * Do NOT hardcode preferredContentType — let CDN serve the best format.
+ * The image CDN auto-negotiates AVIF/WebP from the browser `Accept` header, so do NOT
+ * hardcode a format — the best one is served automatically.
+ *
+ * The URL-building below is pure + framework-agnostic. The zero-config Next.js loader
+ * (`createImageLoader()`) lives in `@doswiftly/storefront-sdk/next`.
  */
 /**
  * Image data from GraphQL API (matches Image type in storefront schema).
@@ -24,6 +32,37 @@ export interface ImageData {
     /** ThumbHash placeholder (base64-encoded ~40 chars). Decode with thumbHashToDataURL() for blur preview. */
     thumbhash?: string | null;
 }
+/**
+ * Base URL of the DoSwiftly image CDN. Platform-owned constant — storefronts never
+ * configure it (the override exists only for tests / non-standard hosting).
+ */
+export declare const IMAGE_CDN_BASE_URL = "https://img.doswiftly.pl";
+/** Per-storefront configuration the image loader needs to build CDN URLs. */
+export interface ImageLoaderConfig {
+    /** Shop identifier — namespaces this storefront's local images in CDN storage. */
+    shopId: string;
+    /** Current deployment version — busts the cache when a `public/` image is replaced under the same name. */
+    version: string;
+    /** Override the image CDN base URL. Defaults to {@link IMAGE_CDN_BASE_URL}. */
+    cdnBase?: string;
+    /**
+     * Framework build-output path prefixes to leave untouched (hashed/immutable assets the
+     * framework already fingerprints). Defaults to {@link FRAMEWORK_BUILD_PREFIXES}.
+     */
+    buildAssetPrefixes?: readonly string[];
+}
+/**
+ * Framework build-output path prefixes — hashed/immutable assets the framework already
+ * fingerprints; never route them through the image CDN. Covers Next/Nuxt/Astro/SvelteKit
+ * (underscore-prefixed → collision-free with merchant `public/` folders). Override via
+ * {@link ImageLoaderConfig.buildAssetPrefixes} for other conventions (e.g. a Vite-based
+ * framework serving build output under `/assets/`, which can collide with `public/assets/`).
+ */
+export declare const FRAMEWORK_BUILD_PREFIXES: readonly ["/_next/", "/_nuxt/", "/_astro/", "/_app/"];
+export declare function buildImageLoaderUrl(config: ImageLoaderConfig, args: {
+    src: string;
+    width: number;
+}): string;
 /**
  * Decode a base64-encoded ThumbHash to a data URL for use as a blur placeholder.
  *

package/dist/core/image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/core/image.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,eAAe;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,2GAA2G;IAC3G,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAOD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAiD5F"}
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/core/image.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,eAAe;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,2GAA2G;IAC3G,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAMD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,6BAA6B,CAAC;AAE7D,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,2GAA2G;IAC3G,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,uDAAwD,CAAC;AA2C9F,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnC,MAAM,CAwDR;AAOD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAiD5F"}

package/dist/core/image.js

@@ -1,12 +1,130 @@
 /**
  * Image types and utilities for DoSwiftly storefronts.
  *
- * GraphQL API returns ready-to-use CDN URLs with transform query params.
- * No client-side loader needed — use `url(transform: { maxWidth: 800 })` in queries.
+ * Two ways images reach the browser:
+ *  - **Product images**: the GraphQL API returns ready-to-use CDN URLs (you may
+ *    request a size with `url(transform: { maxWidth: 800 })`, but with the image
+ *    loader below the size is no longer needed — the loader sets it per srcset entry).
+ *  - **Local images** (your `public/` folder, e.g. a hero or logo used with the
+ *    Next.js `<Image>` component): routed through the image CDN by the loader so they
+ *    are resized + format-negotiated instead of shipped at full size.
  *
- * imgproxy auto-negotiates AVIF/WEBP from browser Accept header (IMGPROXY_AUTO_AVIF=true).
- * Do NOT hardcode preferredContentType — let CDN serve the best format.
+ * The image CDN auto-negotiates AVIF/WebP from the browser `Accept` header, so do NOT
+ * hardcode a format — the best one is served automatically.
+ *
+ * The URL-building below is pure + framework-agnostic. The zero-config Next.js loader
+ * (`createImageLoader()`) lives in `@doswiftly/storefront-sdk/next`.
+ */
+// ---------------------------------------------------------------------------
+// Image loader URL builder (client-side, pure) — feeds the Next.js `<Image>` loader
+// ---------------------------------------------------------------------------
+/**
+ * Base URL of the DoSwiftly image CDN. Platform-owned constant — storefronts never
+ * configure it (the override exists only for tests / non-standard hosting).
+ */
+export const IMAGE_CDN_BASE_URL = 'https://img.doswiftly.pl';
+/**
+ * Framework build-output path prefixes — hashed/immutable assets the framework already
+ * fingerprints; never route them through the image CDN. Covers Next/Nuxt/Astro/SvelteKit
+ * (underscore-prefixed → collision-free with merchant `public/` folders). Override via
+ * {@link ImageLoaderConfig.buildAssetPrefixes} for other conventions (e.g. a Vite-based
+ * framework serving build output under `/assets/`, which can collide with `public/assets/`).
+ */
+export const FRAMEWORK_BUILD_PREFIXES = ['/_next/', '/_nuxt/', '/_astro/', '/_app/'];
+/**
+ * Pure URL builder behind the Next.js image loader. Maps one `<Image>` request
+ * (`src` + the width Next.js asks for) to an image-CDN URL, in three cases:
+ *
+ *  1. **Product image** — `src` is already a CDN URL from the GraphQL API. The
+ *     requested `width` is set per srcset entry, so the same image renders at the
+ *     right size for each viewport (truly responsive).
+ *  2. **Local `public/` image** — `src` is a root-relative path (e.g. `/hero.webp`),
+ *     routed through the CDN (resize + format negotiation) from the storefront's
+ *     uploaded local images.
+ *  3. **Anything else** — Next.js build assets (`/_next/*`), absolute external URLs,
+ *     and `data:` URIs are returned unchanged.
+ *
+ * Framework-agnostic + side-effect free.
+ */
+/**
+ * Image formats the loader routes through the resize CDN. MUST stay in sync with the
+ * backend deploy mirror — the loader may only point `<Image>` at a `public/` path the
+ * deploy actually mirrored. SVG is intentionally excluded: vectors are passed through,
+ * not rasterized.
+ *
+ * @sync-with backend cli.controller.ts `isPublicImageKey`
+ */
+const LOADER_IMAGE_EXTENSIONS = /\.(png|jpe?g|webp|avif|gif)$/i;
+/**
+ * Path prefix of Next.js build-output **media** (images imported in code, e.g.
+ * `import hero from './hero.webp'` → content-hashed bundle). UNLIKE the rest of `/_next/*`
+ * (JS/CSS chunks, left untouched), media images ARE routed through the resize CDN: the deploy
+ * mirrors them to `s/{shopId}/_next-media/{suffix}`. The content hash in the filename is the
+ * version, so the CDN key is immutable (no `?v=` cache-bust).
+ *
+ * @sync-with backend deploy mirror (`_next/static/media/` prefix → `_next-media/` R2 key)
  */
+const NEXT_STATIC_MEDIA_PREFIX = '/_next/static/media/';
+/** Suffix after {@link NEXT_STATIC_MEDIA_PREFIX}, or `null` if `pathname` is not a Next media path. */
+function nextStaticMediaSuffix(pathname) {
+    return pathname.startsWith(NEXT_STATIC_MEDIA_PREFIX) ? pathname.slice(NEXT_STATIC_MEDIA_PREFIX.length) : null;
+}
+export function buildImageLoaderUrl(config, args) {
+    // `||` (not `??`): an empty injected base must still fall back to the platform default.
+    const base = (config.cdnBase || IMAGE_CDN_BASE_URL).replace(/\/+$/, '');
+    const { src, width } = args;
+    // (1) Product image — already an absolute CDN URL. Set the per-srcset width.
+    if (src.startsWith(base)) {
+        try {
+            const url = new URL(src);
+            url.searchParams.set('width', String(width));
+            return url.toString();
+        }
+        catch {
+            return src;
+        }
+    }
+    // (2) Local root-relative image — NOT protocol-relative (`//host`). Two sub-cases:
+    //     (2a) a Next build-output media image (`/_next/static/media/*`), and (2b) a `public/` image.
+    if (src.startsWith('/') && !src.startsWith('//')) {
+        // Not in a deployed storefront (no shopId) → leave untouched, no resize.
+        if (!config.shopId)
+            return src;
+        // Drop any author query/hash — the loader owns `width` (and, for public/, the `?v=`).
+        const pathname = src.replace(/[?#].*$/, '');
+        // Only mirrored image formats. SVG + every non-image (JS/CSS/fonts…) pass through — the
+        // extension gate is the safety that keeps framework build chunks out of the resize CDN.
+        if (!LOADER_IMAGE_EXTENSIONS.test(pathname))
+            return src;
+        // (2a) Next build-output media image. The content hash in the filename IS the version, so
+        // the CDN key is immutable → no `?v=`. The deploy mirrors these to `s/{shopId}/_next-media/`.
+        const mediaSuffix = nextStaticMediaSuffix(pathname);
+        if (mediaSuffix !== null) {
+            // `encodeURIComponent` keeps `..` (unreserved) — harmless while the image CDN is unsigned +
+            // public; if HMAC signing is ever added, strip `..` segments here AND in the public/ branch.
+            const encoded = mediaSuffix.split('/').map(encodeURIComponent).join('/');
+            return `${base}/s/${config.shopId}/_next-media/${encoded}?width=${width}`;
+        }
+        // Any other framework build output (hashed/immutable, NOT mirrored) → untouched.
+        const buildPrefixes = config.buildAssetPrefixes ?? FRAMEWORK_BUILD_PREFIXES;
+        if (buildPrefixes.some((p) => pathname.startsWith(p)))
+            return src;
+        // (2b) Local public/ image. Name-stable key → needs the deploy version for the `?v=` cache-
+        // bust (the source key is overwritten in place when a public/ image is replaced).
+        if (!config.version)
+            return src;
+        // Encode per segment so spaces / non-ASCII filenames match the raw R2 key after the CDN
+        // percent-decodes the path (keeps `/` as the separator).
+        const path = pathname
+            .replace(/^\/+/, '')
+            .split('/')
+            .map(encodeURIComponent)
+            .join('/');
+        return `${base}/s/${config.shopId}/public/${path}?width=${width}&v=${config.version}`;
+    }
+    // (3) Build assets, protocol-relative/external URLs, data URIs — untouched.
+    return src;
+}
 // ---------------------------------------------------------------------------
 // ThumbHash decoder (client-side) — algorithm by Evan Wallace
 // Pure math, zero dependencies, framework-agnostic.

package/dist/core/index.d.ts

@@ -74,7 +74,7 @@ export { matchesRoute, type RouteProtectionConfig } from './auth/routes';
 export { createSetTokenHandler, createClearTokenHandler, createWhoamiHandler, originAllowlistValidator, trustedForwardedHostValidator, } from './auth/handlers';
 export type { OriginValidator, OriginValidatorContext } from './auth/handlers';
 export { createAuthTokenClient, type AuthTokenClient } from './auth/token-client';
-export { type ImageData, thumbHashToDataURL } from './image';
+export { type ImageData, thumbHashToDataURL, IMAGE_CDN_BASE_URL, FRAMEWORK_BUILD_PREFIXES, buildImageLoaderUrl, type ImageLoaderConfig, } from './image';
 export { getOperationName } from './client/operation-name';
 export { hashQuery } from './client/hash';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"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"}

package/dist/core/index.js

@@ -95,8 +95,10 @@ export { matchesRoute } from './auth/routes';
 export { createSetTokenHandler, createClearTokenHandler, createWhoamiHandler, originAllowlistValidator, trustedForwardedHostValidator, } from './auth/handlers';
 // Auth token client (client-side fetch helpers)
 export { createAuthTokenClient } from './auth/token-client';
-// Image types (loaders removed — GraphQL returns ready-to-use CDN URLs with transform params)
-export { thumbHashToDataURL } from './image';
+// Image types + loader URL builder. Product images come pre-transformed from the
+// GraphQL API; the pure `buildImageLoaderUrl` powers the Next.js `<Image>` loader
+// (zero-config wrapper `createImageLoader()` lives in `@doswiftly/storefront-sdk/next`).
+export { thumbHashToDataURL, IMAGE_CDN_BASE_URL, FRAMEWORK_BUILD_PREFIXES, buildImageLoaderUrl, } from './image';
 // Utilities
 export { getOperationName } from './client/operation-name';
 export { hashQuery } from './client/hash';

package/dist/next/image-loader.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Next.js `<Image>` loader for DoSwiftly storefronts.
+ *
+ * Wire it once:
+ * ```ts
+ * // next.config.ts
+ * const nextConfig = { images: { loader: 'custom', loaderFile: './lib/image-loader.ts' } };
+ * ```
+ * ```ts
+ * // lib/image-loader.ts
+ * import { createImageLoader } from '@doswiftly/storefront-sdk/next';
+ * export default createImageLoader();
+ * ```
+ *
+ * Zero configuration: the shop identifier, deployment version, and image-CDN base URL are
+ * read from the public environment variables the DoSwiftly deploy pipeline injects
+ * (`NEXT_PUBLIC_SHOP_ID`, `NEXT_PUBLIC_DEPLOYMENT_COMMIT`, `NEXT_PUBLIC_IMGPROXY_BASE`).
+ * Pass overrides only for tests or non-standard hosting.
+ *
+ * This entry is Next-specific (it reads `NEXT_PUBLIC_*`); the framework-agnostic core (`.`)
+ * stays free of it.
+ */
+import { type ImageLoaderConfig } from '../core/image';
+/** Arguments Next.js passes to a custom image loader. */
+export interface NextImageLoaderArgs {
+    src: string;
+    width: number;
+    /**
+     * Next's per-image quality hint. Not applied — the image CDN negotiates the format
+     * (AVIF/WebP) from the browser `Accept` header and applies a fixed server-side quality,
+     * so `<Image quality>` / `images.qualities` are intentional no-ops on this loader.
+     */
+    quality?: number;
+}
+/**
+ * Create a Next.js custom image loader — the function `images.loaderFile` /
+ * `<Image loader>` expects.
+ *
+ * Each field defaults from the DoSwiftly deploy environment, so the common usage is
+ * argument-free: `export default createImageLoader();`. Any field passed explicitly
+ * overrides the env default (useful in tests / non-standard hosting).
+ *
+ * The env vars are read as LITERAL `process.env.NEXT_PUBLIC_*` member accesses on purpose:
+ * Next/Turbopack only inlines those into the client bundle. A dynamic `process.env[name]`
+ * read is left as-is and resolves to `undefined` in the browser — which would silently
+ * disable the loader and cause a server/client hydration mismatch.
+ */
+export declare function createImageLoader(config?: Partial<ImageLoaderConfig>): (args: NextImageLoaderArgs) => string;
+//# sourceMappingURL=image-loader.d.ts.map

package/dist/next/image-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-loader.d.ts","sourceRoot":"","sources":["../../src/next/image-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE5E,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAClC,CAAC,IAAI,EAAE,mBAAmB,KAAK,MAAM,CAevC"}

package/dist/next/image-loader.js

@@ -0,0 +1,69 @@
+/**
+ * Next.js `<Image>` loader for DoSwiftly storefronts.
+ *
+ * Wire it once:
+ * ```ts
+ * // next.config.ts
+ * const nextConfig = { images: { loader: 'custom', loaderFile: './lib/image-loader.ts' } };
+ * ```
+ * ```ts
+ * // lib/image-loader.ts
+ * import { createImageLoader } from '@doswiftly/storefront-sdk/next';
+ * export default createImageLoader();
+ * ```
+ *
+ * Zero configuration: the shop identifier, deployment version, and image-CDN base URL are
+ * read from the public environment variables the DoSwiftly deploy pipeline injects
+ * (`NEXT_PUBLIC_SHOP_ID`, `NEXT_PUBLIC_DEPLOYMENT_COMMIT`, `NEXT_PUBLIC_IMGPROXY_BASE`).
+ * Pass overrides only for tests or non-standard hosting.
+ *
+ * This entry is Next-specific (it reads `NEXT_PUBLIC_*`); the framework-agnostic core (`.`)
+ * stays free of it.
+ */
+import { buildImageLoaderUrl } from '../core/image';
+/**
+ * Create a Next.js custom image loader — the function `images.loaderFile` /
+ * `<Image loader>` expects.
+ *
+ * Each field defaults from the DoSwiftly deploy environment, so the common usage is
+ * argument-free: `export default createImageLoader();`. Any field passed explicitly
+ * overrides the env default (useful in tests / non-standard hosting).
+ *
+ * The env vars are read as LITERAL `process.env.NEXT_PUBLIC_*` member accesses on purpose:
+ * Next/Turbopack only inlines those into the client bundle. A dynamic `process.env[name]`
+ * read is left as-is and resolves to `undefined` in the browser — which would silently
+ * disable the loader and cause a server/client hydration mismatch.
+ */
+export function createImageLoader(config) {
+    const resolved = {
+        shopId: config?.shopId ?? process.env.NEXT_PUBLIC_SHOP_ID ?? '',
+        version: config?.version ?? process.env.NEXT_PUBLIC_DEPLOYMENT_COMMIT ?? '',
+        cdnBase: config?.cdnBase ?? process.env.NEXT_PUBLIC_IMGPROXY_BASE,
+    };
+    // Dev-only hint: surface raster images that the loader can't optimize (an external host, or
+    // a build asset outside `/_next/static/media/`). Only when a shopId is resolved — without one
+    // (local `doswiftly dev`) every image is an expected passthrough, so warning would be noise.
+    const warned = resolved.shopId && process.env.NODE_ENV !== 'production' ? new Set() : null;
+    return (args) => {
+        const url = buildImageLoaderUrl(resolved, args);
+        if (warned && url === args.src)
+            warnImageBypass(args.src, warned);
+        return url;
+    };
+}
+/**
+ * Dev-only: warn once per src for an EXTERNAL raster image used in `<Image>` — it bypasses the
+ * DoSwiftly image CDN (served as-is, no resize / format negotiation). Local `/…` images (`public/`
+ * + code-imported `/_next/static/media/`) are routed automatically; a local image reaching here
+ * only means a missing platform env (a config issue, not a footgun), so it is NOT flagged. SVG
+ * (vector) and `data:` URIs are not bypasses.
+ */
+function warnImageBypass(src, warned) {
+    if (warned.has(src) || !/^(https?:)?\/\//.test(src) || !/\.(png|jpe?g|webp|avif|gif)(\?|#|$)/i.test(src))
+        return;
+    warned.add(src);
+    console.warn(`[DoSwiftly] <Image src="${src}"> is an external URL, so it loads at full size and is NOT ` +
+        `optimized (no automatic resizing or format conversion). To optimize it: move the image into ` +
+        `your public/ folder and use a root-relative src like "/photo.jpg", or use a product image ` +
+        `whose URL comes from the API (those are already optimized CDN URLs).`);
+}

package/dist/next/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @doswiftly/storefront-sdk/next — Next.js-specific helpers.
+ *
+ * Utilities that depend on Next.js conventions (the `<Image>` custom loader and
+ * build-time public env vars). Kept out of the framework-agnostic core (`.`) so the
+ * core stays portable to Node, Edge, Deno, and Bun.
+ */
+export { createImageLoader, type NextImageLoaderArgs } from './image-loader';
+//# sourceMappingURL=index.d.ts.map

package/dist/next/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/next/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/next/index.js

@@ -0,0 +1,11 @@
+/**
+ * @doswiftly/storefront-sdk/next — Next.js-specific helpers.
+ *
+ * Utilities that depend on Next.js conventions (the `<Image>` custom loader and
+ * build-time public env vars). Kept out of the framework-agnostic core (`.`) so the
+ * core stays portable to Node, Edge, Deno, and Bun.
+ */
+export { createImageLoader } from './image-loader';
+// The pure builder + its config/base (`buildImageLoaderUrl`, `IMAGE_CDN_BASE_URL`,
+// `ImageLoaderConfig`) are framework-agnostic and live on the core entry
+// (`@doswiftly/storefront-sdk`) — import them from there, not from `/next`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-sdk",
-  "version": "22.5.1",
+  "version": "22.7.0",
   "description": "Storefront runtime SDK for DoSwiftly Commerce — layered transport, middleware pipeline, React providers, Zustand stores, cache strategies. 0 runtime dependencies in core.",
   "type": "module",
   "sideEffects": false,
@@ -23,6 +23,10 @@
       "types": "./dist/react/server/index.d.ts",
       "default": "./dist/react/server/index.js"
     },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "default": "./dist/next/index.js"
+    },
     "./cache": {
       "types": "./dist/core/cache.d.ts",
       "default": "./dist/core/cache.js"