@doswiftly/storefront-sdk 22.6.0 → 22.8.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 22.8.0
+
+### Minor Changes
+
+- 9039ba1: Add `getAssetPrefix()` for serving your build's static assets from a CDN domain.
+
+  **Why**: A build's JavaScript, CSS, and font files (`/_next/static/*`) are content-hashed and immutable. Serving them from a CDN domain — rather than your app origin — makes them cache-friendly and keeps them off your storefront server's request path.
+
+  **Additive (backward-compatible)**: a new export from `@doswiftly/storefront-sdk/next`. Nothing changes until you opt in.
+
+  **Usage** — add two lines to `next.config`:
+
+  ```ts
+  // next.config.ts
+  import { getAssetPrefix } from "@doswiftly/storefront-sdk/next";
+
+  const nextConfig = {
+    assetPrefix: getAssetPrefix(),
+    crossOrigin: "anonymous",
+    // ...your existing config
+  };
+  export default nextConfig;
+  ```
+
+  `getAssetPrefix()` returns the CDN base injected by the deploy pipeline (namespaced to your shop), or `undefined` in development and on deploys without a CDN configured — so `next dev` and un-provisioned deploys keep serving assets from the app origin. Pair it with `crossOrigin: 'anonymous'`: the assets then load cross-origin and the CDN sends the matching CORS header (required for fonts).
+
+  **Migration checklist for existing storefronts**:
+  - [ ] Add `assetPrefix: getAssetPrefix()` and `crossOrigin: 'anonymous'` to `next.config`.
+  - [ ] Redeploy — the next build's static assets are served from the CDN.
+
+  (`@doswiftly/storefront-operations` is version-synced with the SDK; no operation changes in this release.)
+
+## 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

package/README.md

@@ -774,7 +774,8 @@ The loader is global and handles each `<Image src>` by category:
 |-------|----------|
 | 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 |
-| Build asset (`/_next/*`), absolute external URL, `data:` URI | Returned unchanged |
+| 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

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

@@ -1 +1 @@
-{"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;AA2B9F,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnC,MAAM,CAuCR;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

@@ -55,6 +55,20 @@ export const FRAMEWORK_BUILD_PREFIXES = ['/_next/', '/_nuxt/', '/_astro/', '/_ap
  * @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/static/media/{suffix}` (the path is kept 1:1). 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/` path mirrored 1:1 into the 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(/\/+$/, '');
@@ -70,26 +84,42 @@ export function buildImageLoaderUrl(config, args) {
             return src;
         }
     }
-    // (2) Local public/ image — root-relative, NOT protocol-relative (`//host`).
+    // (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 shop/version) → leave untouched, no resize.
-        if (!config.shopId || !config.version)
+        // 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 the `?v=` cache-bust.
+        // Drop any author query/hash — the loader owns `width` (and, for public/, the `?v=`).
         const pathname = src.replace(/[?#].*$/, '');
-        // Only mirrored image formats; never a framework build asset (any supported framework).
+        // 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/static/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/static/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)) || !LOADER_IMAGE_EXTENSIONS.test(pathname))
+        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).
+        // 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('/');
-        // Name-stable CDN key; the deploy version rides in `?v=` to bust the CDN cache when a
-        // public/ image is replaced under the same name (the source key is overwritten in place).
         return `${base}/s/${config.shopId}/public/${path}?width=${width}&v=${config.version}`;
     }
     // (3) Build assets, protocol-relative/external URLs, data URIs — untouched.

package/dist/next/asset-prefix.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Next.js `assetPrefix` for DoSwiftly storefronts.
+ *
+ * Wire it once:
+ * ```ts
+ * // next.config.ts
+ * import { getAssetPrefix } from '@doswiftly/storefront-sdk/next';
+ * const nextConfig = { assetPrefix: getAssetPrefix(), crossOrigin: 'anonymous' };
+ * ```
+ *
+ * Your static assets (`/_next/static/*` — JavaScript, CSS, and fonts) are then served from your
+ * storefront's own CDN domain instead of the app origin: cache-friendly, immutable, and off the
+ * request path of your storefront server. The CDN base is injected by the DoSwiftly deploy
+ * pipeline — you don't configure it.
+ *
+ * Returns `undefined` in development (so `doswiftly dev` serves assets locally for fast refresh) and
+ * whenever the pipeline hasn't injected a CDN base (so an un-provisioned deploy keeps serving
+ * assets from the app origin). Either way there is no setup and nothing to break.
+ *
+ * Pair it with `crossOrigin: 'anonymous'`: assets then load cross-origin and the CDN sends the
+ * matching CORS header (required for fonts).
+ */
+export declare function getAssetPrefix(): string | undefined;
+//# sourceMappingURL=asset-prefix.d.ts.map

package/dist/next/asset-prefix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-prefix.d.ts","sourceRoot":"","sources":["../../src/next/asset-prefix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAKnD"}

package/dist/next/asset-prefix.js

@@ -0,0 +1,29 @@
+/**
+ * Next.js `assetPrefix` for DoSwiftly storefronts.
+ *
+ * Wire it once:
+ * ```ts
+ * // next.config.ts
+ * import { getAssetPrefix } from '@doswiftly/storefront-sdk/next';
+ * const nextConfig = { assetPrefix: getAssetPrefix(), crossOrigin: 'anonymous' };
+ * ```
+ *
+ * Your static assets (`/_next/static/*` — JavaScript, CSS, and fonts) are then served from your
+ * storefront's own CDN domain instead of the app origin: cache-friendly, immutable, and off the
+ * request path of your storefront server. The CDN base is injected by the DoSwiftly deploy
+ * pipeline — you don't configure it.
+ *
+ * Returns `undefined` in development (so `doswiftly dev` serves assets locally for fast refresh) and
+ * whenever the pipeline hasn't injected a CDN base (so an un-provisioned deploy keeps serving
+ * assets from the app origin). Either way there is no setup and nothing to break.
+ *
+ * Pair it with `crossOrigin: 'anonymous'`: assets then load cross-origin and the CDN sends the
+ * matching CORS header (required for fonts).
+ */
+export function getAssetPrefix() {
+    // Development must serve assets from the dev server (fast refresh) — never the CDN.
+    if (process.env.NODE_ENV === "development")
+        return undefined;
+    // Literal member access (read at build time inside next.config). Empty / unset → app origin.
+    return process.env.DOSWIFTLY_ASSET_PREFIX || undefined;
+}

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

@@ -1 +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,CAOvC"}
+{"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

@@ -40,5 +40,30 @@ export function createImageLoader(config) {
         version: config?.version ?? process.env.NEXT_PUBLIC_DEPLOYMENT_COMMIT ?? '',
         cdnBase: config?.cdnBase ?? process.env.NEXT_PUBLIC_IMGPROXY_BASE,
     };
-    return (args) => buildImageLoaderUrl(resolved, args);
+    // 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

@@ -6,4 +6,5 @@
  * core stays portable to Node, Edge, Deno, and Bun.
  */
 export { createImageLoader, type NextImageLoaderArgs } from './image-loader';
+export { getAssetPrefix } from './asset-prefix';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"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;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/next/index.js

@@ -6,6 +6,7 @@
  * core stays portable to Node, Edge, Deno, and Bun.
  */
 export { createImageLoader } from './image-loader';
+export { getAssetPrefix } from './asset-prefix';
 // 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.6.0",
+  "version": "22.8.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,