@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

package/package.json

@@ -1,125 +1,155 @@
 {
   "name": "@shopify/hydrogen",
-  "publishConfig": {
-    "access": "public",
-    "@shopify:registry": "https://registry.npmjs.org"
-  },
-  "type": "module",
-  "version": "2026.4.5",
+  "version": "2026.10.0-preview.2",
+  "description": "Framework-agnostic Shopify storefront SDK and agent skills.",
   "license": "MIT",
-  "main": "dist/index.cjs",
-  "module": "dist/production/index.js",
-  "types": "dist/production/index.d.ts",
-  "sideEffects": false,
+  "author": "Shopify",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Shopify/hydrogen.git",
     "directory": "packages/hydrogen"
   },
+  "bin": {
+    "hydrogen": "./bin/hydrogen.mjs"
+  },
+  "files": [
+    "README.md",
+    "bin",
+    "dist",
+    "skills"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/core/index.mjs",
+  "types": "./dist/core/index.d.mts",
   "exports": {
     ".": {
-      "types": "./dist/production/index.d.ts",
-      "module": {
-        "development": "./dist/development/index.js",
-        "default": "./dist/production/index.js"
+      "types": {
+        "development": "./dist/development/core/development.d.mts",
+        "default": "./dist/core/index.d.mts"
       },
-      "require": "./dist/index.cjs",
       "import": {
-        "development": "./dist/development/index.js",
-        "default": "./dist/production/index.js"
+        "development": "./dist/development/core/development.mjs",
+        "default": "./dist/core/index.mjs"
       },
       "default": {
-        "development": "./dist/development/index.js",
-        "default": "./dist/production/index.js"
+        "development": "./dist/development/core/development.mjs",
+        "default": "./dist/core/index.mjs"
       }
     },
-    "./vite": {
-      "types": "./dist/vite/plugin.d.ts",
-      "default": "./dist/vite/plugin.js"
-    },
-    "./oxygen": {
-      "types": "./dist/oxygen/index.d.ts",
-      "default": "./dist/oxygen/index.js"
+    "./customer-account": {
+      "types": "./dist/customer-account/index.d.mts",
+      "import": "./dist/customer-account/index.mjs"
     },
-    "./storefront-api-types": "./dist/storefront-api-types.d.ts",
-    "./storefront.schema.json": "./dist/storefront.schema.json",
     "./customer-account-api-types": "./dist/customer-account-api-types.d.ts",
     "./customer-account.schema.json": "./dist/customer-account.schema.json",
-    "./react-router-types": {
-      "types": "./dist/react-router.d.ts"
+    "./package.json": "./package.json",
+    "./skills/*": "./skills/*",
+    "./storefront-api-types": "./dist/storefront-api-types.d.ts",
+    "./storefront.schema.json": "./dist/storefront.schema.json",
+    "./ts-plugin": {
+      "types": "./dist/ts-plugin/index.d.cts",
+      "require": "./dist/ts-plugin/index.cjs",
+      "default": "./dist/ts-plugin/index.cjs"
     },
-    "./react-router-preset": {
-      "types": "./dist/production/react-router-preset.d.ts",
-      "import": {
-        "development": "./dist/development/react-router-preset.js",
-        "default": "./dist/production/react-router-preset.js"
+    "./vite": {
+      "types": "./dist/vite/index.d.mts",
+      "import": "./dist/vite/index.mjs"
+    },
+    "./react": {
+      "types": {
+        "development": "./dist/development/react/index.d.mts",
+        "default": "./dist/react/index.d.mts"
       },
-      "default": "./dist/production/react-router-preset.js"
+      "import": {
+        "development": "./dist/development/react/index.mjs",
+        "default": "./dist/react/index.mjs"
+      }
     },
-    "./package.json": "./package.json"
-  },
-  "typesVersions": {
-    "*": {
-      "storefront-api-types": [
-        "./dist/storefront-api-types.d.ts"
-      ],
-      "customer-account-api-types": [
-        "./dist/customer-account-api-types.d.ts"
-      ]
+    "./vue": {
+      "types": {
+        "development": "./dist/development/vue/index.d.mts",
+        "default": "./dist/vue/index.d.mts"
+      },
+      "import": {
+        "development": "./dist/development/vue/index.mjs",
+        "default": "./dist/vue/index.mjs"
+      }
     }
   },
-  "files": [
-    "dist"
-  ],
+  "publishConfig": {
+    "@shopify:registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
   "dependencies": {
-    "content-security-policy-builder": "^2.2.0",
-    "flame-chart-js": "2.3.1",
-    "isbot": "^5.1.21",
-    "source-map-support": "^0.5.21",
-    "type-fest": "^4.33.0",
-    "use-resize-observer": "^9.1.0",
-    "worktop": "^0.7.3",
-    "@shopify/graphql-client": "1.4.1",
-    "@shopify/hydrogen-react": "2026.4.3"
+    "gql.tada": "1.9.2"
   },
   "devDependencies": {
-    "react-router": "7.16.0",
-    "@react-router/dev": "7.16.0",
-    "@shopify/generate-docs": "1.2.2",
-    "@testing-library/jest-dom": "^6.6.3",
-    "@types/node": "22.19.15",
-    "@types/react": "^18.3.28",
-    "@types/react-dom": "^18.3.7",
-    "@testing-library/react": "^14.0.0",
-    "@types/source-map-support": "^0.5.10",
-    "formdata-polyfill": "^4.0.10",
-    "graphql": "^16.12.0",
-    "happy-dom": "^20.8.9",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "schema-dts": "^1.1.2",
-    "vitest": "^3.2.4",
-    "@shopify/hydrogen-codegen": "0.3.3"
+    "@graphql-codegen/cli": "^7.0.0",
+    "@graphql-codegen/introspection": "^6.0.0",
+    "@graphql-codegen/typescript": "^6.0.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vue/test-utils": "^2.4.0",
+    "graphql": "^16.13.2",
+    "happy-dom": "^20.9.0",
+    "magic-string": "^0.30.21",
+    "oxc-parser": "0.135.0",
+    "oxc-walker": "^1.0.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "tsdown": "^0.21.10",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.7",
+    "vitest": "^3.0.0"
   },
   "peerDependencies": {
-    "react-router": "~7.16.0",
-    "@react-router/dev": "~7.16.0",
-    "react": "^18.3.1 || ~19.0.3 || ~19.1.4 || ^19.2.3",
-    "vite": "^5.1.0 || ^6.2.1 || ^7.0.0 || ^8.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
+    "vue": "^3.5.0"
   },
   "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
     "vite": {
       "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "shopify": {
+    "cli": {
+      "disabledCommands": [
+        "hydrogen:build",
+        "hydrogen:check",
+        "hydrogen:codegen",
+        "hydrogen:debug:cpu",
+        "hydrogen:dev",
+        "hydrogen:g",
+        "hydrogen:generate:route",
+        "hydrogen:generate:routes",
+        "hydrogen:preview",
+        "hydrogen:setup",
+        "hydrogen:setup:css",
+        "hydrogen:setup:markets",
+        "hydrogen:setup:vite",
+        "hydrogen:shortcut",
+        "hydrogen:upgrade"
+      ]
     }
   },
   "scripts": {
-    "build": "tsup --clean",
-    "dev": "tsup --watch ./src --watch ../../node_modules/@shopify/hydrogen-react/dist/browser-prod/index.mjs",
+    "build": "tsdown && node scripts/copy-generated-graphql-assets.ts",
+    "dev": "tsdown --watch ./src",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "build-docs": "sh ./docs/build-docs.sh && pnpm run format",
-    "format": "prettier --write \"{src,docs}/**/*\" --ignore-unknown",
-    "preview-docs": "pnpm --dir ../../docs/preview run dev"
+    "libcheck": "node scripts/libcheck-package.ts",
+    "test": "pnpm run build && vitest run",
+    "test:watch": "pnpm run build && vitest",
+    "test:types": "pnpm run build && vitest --typecheck --run",
+    "codegen": "graphql-codegen --config codegen.ts && gql.tada generate-output --tsconfig tsconfig.codegen.json",
+    "postcodegen": "node scripts/postprocess-tada-env.ts && oxfmt src/graphql/generated/*.d.ts src/graphql/generated/*.json"
   }
 }

package/skills/hydrogen-analytics/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: hydrogen-analytics
+description: >
+  Guide for adding or reviewing Hydrogen storefront analytics. Use when working
+  with ShopifyScripts analytics, AnalyticsEvent, consent mode, page/product/
+  collection/search/cart view events, cart update tracking, custom analytics
+  destinations, or framework route-change analytics wiring.
+---
+
+# Storefront Analytics
+
+Hydrogen's analytics bus owns the event API, event normalization, and consent-gated destination replay. ShopifyScripts owns Shopify consent setup, analytics CDN loading, and deprecated cookie compatibility. App code owns when to publish route/view events and when to call cart delta tracking.
+
+## Framework References
+
+Before wiring route events, check whether this skill has a reference file for the app's framework in `references/`. If one exists, read it and use that framework's route-change and lifecycle primitives. If there is no matching reference, keep the core singleton below and adapt page-view, product-view, collection-view, search-view, and cart tracking to the app's own route lifecycle.
+
+Prerequisite: analytics depends on the same-origin SFAPI proxy (see `hydrogen-request-handlers`) so the browser can observe tracking values from Storefront API responses. Without it, analytics falls back to deprecated JavaScript-visible cookies and session continuity into checkout breaks — treat it as incomplete until the proxy is wired. Key consent setup: Shopify Customer Privacy controls destination delivery in production. Raw subscribers can observe events before consent; destinations receive only consent-allowed replay. Do not bypass Customer Privacy consent gating in production.
+
+## Core Pattern
+
+Render Shopify runtime scripts once from the app root/document head with the same resolved market used by Storefront API requests. Use `ShopifyScripts` from your framework binding if it exports one, or `getShopifyScriptTags()` / `renderShopifyScriptTags()` from core in other framework heads. Pass the `shop` object matching the `ShopifyScriptsShop` type, and `i18n` matching the `ShopifyScriptsI18n` type and serialize them into ShopifyScripts. — declare them as constants with type annotations to keep errors located close to the source of writing. The analytics bus is created by default; pass `analytics` only for optional bus configuration such as `customData`. Do not pass market `country` or `language` through analytics consent config.
+
+Read one browser-lazy singleton from the Shopify global created by `ShopifyScripts`:
+
+```ts
+import {
+  AnalyticsEvent,
+  type StorefrontAnalytics,
+  trackCartAnalytics,
+} from "@shopify/hydrogen";
+
+export { AnalyticsEvent };
+
+let bus: StorefrontAnalytics | null = null;
+
+export function getAnalytics(): StorefrontAnalytics | null {
+  if (typeof window === "undefined") return null;
+  bus ??= window.Shopify?.analytics ?? null;
+  return bus;
+}
+
+export { trackCartAnalytics };
+```
+
+Read `shop` and `i18n` values on the server and pass them to `ShopifyScripts`. Do not read env APIs in browser modules.
+
+In the ShopifyScripts `analytics` config, `channel` is optional and defaults to `"hydrogen"`. The `"hydrogen"` channel is the one that requires `storefrontId` — it is pulled from the ShopifyScripts `shop` config into analytics payloads. Headless storefronts pass `channel: "headless"` in the ShopifyScripts `analytics` config; the analytics payload then omits `storefrontId`, but `shop.storefrontId` itself is still required (pass `"0"` when the app has no storefront ID).
+
+## Publish Events
+
+Publish these from route/page boundaries:
+
+- `PAGE_VIEWED` on each page transition.
+- `PRODUCT_VIEWED` when product data is resolved on a product page.
+- `COLLECTION_VIEWED` when collection data is resolved.
+- `SEARCH_VIEWED` when a non-empty search term has results metadata.
+- `CART_VIEWED` when the full cart page or cart drawer is viewed.
+- Wire cart tracking once per cart store lifecycle with `trackCartAnalytics(cartStore)` — React apps use the `useCartAnalytics()` hook from `@shopify/hydrogen/react` and Vue apps use the `useCartAnalytics()` composable from `@shopify/hydrogen/vue`; both call it with the provider's cart store and clean up on unmount. The tracker subscribes to the cart store itself, skips pending/revalidating/note updates, publishes cart delta events on confirmed cart changes, and returns an unsubscribe function. Call it from a client-only effect (`useEffect` / `onMounted`), never at cart-store creation time — it throws when `window.Shopify.analytics` is missing (SSR). Do not manually publish cart delta events.
+
+The bus defaults `shop` from the top-level `shop` config passed to ShopifyScripts; pass `shop` in an event payload only when intentionally overriding that configured value. Shopify analytics reads language and currency from `window.Shopify.locale` and `window.Shopify.currency.active`.
+
+Required product analytics fields include Shopify Product GID, ProductVariant GID when available, title, price, vendor, quantity, and variant title.
+
+## Rules
+
+- Let Shopify Customer Privacy control destination delivery in production.
+- Initialize one single bus per page lifetime through ShopifyScripts.
+- Raw subscribers can observe events before consent; destinations receive only consent-allowed replay.
+- Render ShopifyScripts before route components publish events.
+- Do not dispatch server-side analytics through this browser bus.
+- Keep ShopifyScripts i18n aligned with the resolved market when the storefront uses markets.
+
+## Verify
+
+- Page view fires on initial load and client navigations.
+- Product, collection, search, and cart view events fire once per relevant route data change.
+- Confirmed cart data changes flow through `trackCartAnalytics(cartStore)` (React/Vue bindings: `useCartAnalytics()`), and the cart query includes `updatedAt`.
+- Consent-denied visitors do not deliver destination events.
+- No browser module reads private or server-only env variables.

package/skills/hydrogen-analytics/references/react.md

@@ -0,0 +1,160 @@
+# React Frameworks
+
+Use ShopifyScripts in the root layout/head, then publish events from client-side tracker components.
+
+## Root Tracker
+
+Server root/layout resolves safe `shop` and `i18n` data and passes it to ShopifyScripts.
+
+```tsx
+<ShopifyScripts
+  shop={{
+    shopId: env.SHOP_ID,
+    storefrontId: env.PUBLIC_STOREFRONT_ID ?? "0",
+    myshopifyDomain: env.PUBLIC_STORE_DOMAIN,
+  }}
+  i18n={{ country: market.country, language: market.language, currency: market.currencyCode }}
+  consent={{ mode: "default-banner" }}
+/>
+```
+
+Do not query `localization.language` just to echo the language already passed to `@inContext`. If the app only knows country/language and does not have a market currency code, add `currencyCode` to the app's market config or query `localization { country { currency { isoCode } } }` as a fallback.
+
+```tsx
+import { useEffect } from "react";
+import { AnalyticsEvent, getAnalytics } from "../lib/analytics";
+
+export function AnalyticsTracker() {
+  useEffect(() => {
+    const analytics = getAnalytics();
+    if (!analytics) return;
+    analytics.publish(AnalyticsEvent.PAGE_VIEWED);
+  }, []);
+
+  return null;
+}
+```
+
+Add `"use client"` only when this component lives in a Next.js App Router client component file.
+
+For real route tracking, include the framework location in the effect dependency. In React Router, read `useLocation()` and key the effect by `location.pathname + location.search`. In Next App Router, read `usePathname()` and `useSearchParams()` in a client component wrapped in `Suspense`, then key the effect by both values. View events infer `url` from `window.location.href`; pass `url` only for an explicit override.
+
+Cart analytics should publish from the confirmed cart state. If a component reads cart state directly, wait while `cart.revalidating === true || cart.pending.cost === true || cart.pending.note` is true so optimistic or revalidating cart changes do not publish as settled analytics.
+
+```tsx
+// app/layout.tsx
+import { Suspense } from "react";
+import { AnalyticsTracker } from "./components/AnalyticsTracker";
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Suspense fallback={null}>
+          <AnalyticsTracker />
+        </Suspense>
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+```tsx
+// app/components/AnalyticsTracker.tsx
+"use client";
+
+import { usePathname, useSearchParams } from "next/navigation";
+import { useEffect } from "react";
+import { AnalyticsEvent, getAnalytics } from "../lib/analytics";
+
+export function AnalyticsTracker() {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const pageKey = `${pathname}?${searchParams?.toString() ?? ""}`;
+
+  useEffect(() => {
+    const analytics = getAnalytics();
+    if (!analytics) return;
+    analytics.publish(AnalyticsEvent.PAGE_VIEWED);
+  }, [pageKey]);
+
+  return null;
+}
+```
+
+## Product Viewed
+
+Publish after product route data is available:
+
+```tsx
+function ProductViewedTracker({ product, selectedVariant }: Props) {
+  useEffect(() => {
+    const analytics = getAnalytics();
+    if (!analytics) return;
+
+    analytics.publish(AnalyticsEvent.PRODUCT_VIEWED, {
+      products: [
+        {
+          id: product.id,
+          title: product.title,
+          price:
+            selectedVariant?.price.amount ??
+            product.selectedOrFirstAvailableVariant?.price.amount ??
+            product.priceRange.minVariantPrice.amount,
+          vendor: product.vendor,
+          variantId:
+            selectedVariant?.id ??
+            product.selectedOrFirstAvailableVariant?.id ??
+            product.id,
+          variantTitle:
+            selectedVariant?.title ??
+            product.selectedOrFirstAvailableVariant?.title ??
+            product.title,
+          quantity: 1,
+          sku: selectedVariant?.sku,
+        },
+      ],
+    });
+  }, [product.handle]);
+
+  return null;
+}
+```
+
+Prefer ProductVariant GID for `variantId`. Falling back to product ID should be treated as incomplete data.
+
+## Collection And Search Viewed
+
+Publish collection view when collection identity changes:
+
+```tsx
+analytics.publish(AnalyticsEvent.COLLECTION_VIEWED, {
+  collection: { id: collection.id, handle: collection.handle },
+});
+```
+
+Publish search view only for non-empty terms:
+
+```tsx
+if (term) {
+  analytics.publish(AnalyticsEvent.SEARCH_VIEWED, {
+    searchTerm: term,
+    searchResults: { totalCount },
+  });
+}
+```
+
+## Cart Updates
+
+Use the `useCartAnalytics()` hook from the React binding — rendered inside `CartProvider`, it calls `trackCartAnalytics(store)` in an effect and cleans up on unmount. Outside the binding, call `trackCartAnalytics(store)` once with the cart store from a client-only effect (`useEffect`) — never at cart-store creation time, since it throws when `window.Shopify.analytics` is missing during SSR. It subscribes itself, skips pending/revalidating/note updates, derives cart delta events from confirmed cart changes, returns an unsubscribe function, and uses the global analytics bus created by ShopifyScripts. Do not manually publish `product_added_to_cart`.
+
+Publish `CART_VIEWED` when the cart page or drawer is viewed. The cart payload is `AnalyticsCart | null`: when a compatible cart is available, include `id`, `updatedAt`, and connection-shaped `lines`; otherwise pass `cart: null` instead of a partial cart.
+
+```tsx
+analytics.publish(AnalyticsEvent.CART_VIEWED, {
+  cart: analyticsCart ?? null,
+});
+```
+
+If the app uses Hydrogen's cart store type directly, convert it at the app boundary before publishing analytics. Only pass settled cart lines that include product IDs, vendor, and variant price fields.

package/skills/hydrogen-analytics/references/vue.md

@@ -0,0 +1,80 @@
+# Vue And Nuxt
+
+Use `ShopifyScripts` in the app root/head, then read the shared bus from the Shopify global.
+
+## Singleton
+
+```ts
+import {
+  AnalyticsEvent,
+  type StorefrontAnalytics,
+} from "@shopify/hydrogen";
+
+export { AnalyticsEvent };
+
+let analytics: StorefrontAnalytics | null = null;
+
+export function getAnalytics() {
+  if (!import.meta.client) return null;
+  analytics ??= window.Shopify?.analytics ?? null;
+  return analytics;
+}
+```
+
+## Nuxt Client Plugin
+
+Render `ShopifyScripts` with top-level `shop` and `i18n` in the app root/head. A client plugin can then read the global bus directly:
+
+```ts
+export default defineNuxtPlugin(() => {
+  const analytics = getAnalytics();
+  analytics?.addDestination({
+    name: "example-console-logger",
+    setup({ subscribe }) {
+      return subscribe(AnalyticsEvent.PAGE_VIEWED, (payload) => {
+        console.log("[analytics] page_viewed", payload);
+      });
+    },
+  });
+});
+```
+
+Do not expose private tokens through runtime public config.
+
+## Page Views
+
+Use a client plugin or root component watcher. View events infer `url` from `window.location.href`; pass `url` only for an explicit override:
+
+```ts
+export default defineNuxtPlugin(() => {
+  const router = useRouter();
+  router.afterEach(() => {
+    const analytics = getAnalytics();
+    if (!analytics) return;
+    analytics.publish(AnalyticsEvent.PAGE_VIEWED);
+  });
+});
+```
+
+## Product, Collection, Search
+
+Use `onMounted` or `watch` keyed on resolved route data:
+
+```ts
+onMounted(() => {
+  const analytics = getAnalytics();
+  if (!analytics) return;
+  analytics.publish(AnalyticsEvent.SEARCH_VIEWED, {
+    searchTerm: term.value,
+    searchResults: { totalCount: totalCount.value },
+  });
+});
+```
+
+Avoid publishing view events before server data is available.
+
+## Cart Updates
+
+Call the `useCartAnalytics()` composable from `@shopify/hydrogen/vue` in a component rendered inside the `CartProvider` returned by `createCartComponents()` (the Vue entry exports no standalone `CartProvider`). It subscribes the provider's cart store on mount, skips pending/revalidating/note updates, publishes derived cart delta events through the global analytics bus on confirmed cart changes, and unsubscribes when the component is disposed. If the app owns its cart store directly (`createCartStore` from `@shopify/hydrogen`), call `trackCartAnalytics(store)` once instead, from a client-only effect (`onMounted`) — never at cart-store creation time, since it throws when `window.Shopify.analytics` is missing during SSR. It returns an unsubscribe function.
+
+If a component reads cart state directly, wait while `cart.revalidating === true || cart.pending.cost === true || cart.pending.note` is true so optimistic or revalidating cart changes do not publish as settled analytics.