@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/react/shopify-scripts.d.mts

@@ -2,11 +2,23 @@ import { ShopifyRoutesOptions, ShopifyScriptTagsOptions } from "../core/shopify-
 import * as React from "react";
 
 //#region src/react/shopify-scripts.d.ts
-type ShopifyScriptsProps = ShopifyScriptTagsOptions & {
+/**
+ * Props for the `ShopifyScripts` component in React and Vue. The component renders Shopify's script
+ * tags and starts the scripts in the browser after hydration. The component starts the scripts
+ * once, with the first props. Later prop changes don't restart the scripts.
+ *
+ * In Next.js App Router, render the component from a client component when you pass a consent `setup` function. Function props can't cross the server-to-client boundary.
+ *
+ * @publicDocs
+ */
+interface ShopifyScriptsProps extends ShopifyScriptTagsOptions {
+  /** Navigates after Shopify's scripts resolve a URL to your app's route. Defaults to a full page load. */
   navigate?: ShopifyRoutesOptions["navigate"];
+  /** Your app's custom route templates, which Shopify's scripts use to match storefront URLs. */
   routes?: ShopifyRoutesOptions["routes"];
+  /** Loads Shopify's WebMCP tools when the browser supports WebMCP. Defaults to `true`. */
   webMcp?: boolean;
-};
+}
 declare module "react" {
   namespace JSX {
     interface IntrinsicElements {
@@ -14,6 +26,15 @@ declare module "react" {
     }
   }
 }
+/**
+ * Renders Shopify's script tags and starts the scripts in the browser after hydration. The component starts the scripts once, with the first props. Later prop changes don't restart the scripts.
+ *
+ * `ShopifyScripts` is a client component. In Next.js App Router, render it from a client component when you pass a consent `setup` function. Function props can't cross the server-to-client boundary.
+ *
+ * @param options - The script tag options, plus the consent, route, and WebMCP settings for starting the scripts.
+ * @returns Shopify's link and script tags, with the link tags first.
+ * @publicDocs
+ */
 declare function ShopifyScripts(options: ShopifyScriptsProps): React.FunctionComponentElement<React.FragmentProps>;
 //#endregion
 export { ShopifyScripts, ShopifyScriptsProps };

package/dist/react/shopify-scripts.mjs

@@ -5,6 +5,15 @@ import { getShopifyScriptTags } from "../core/shopify-scripts/index.mjs";
 import { Fragment, createElement, useEffect } from "react";
 
 //#region src/react/shopify-scripts.tsx
+/**
+* Renders Shopify's script tags and starts the scripts in the browser after hydration. The component starts the scripts once, with the first props. Later prop changes don't restart the scripts.
+*
+* `ShopifyScripts` is a client component. In Next.js App Router, render it from a client component when you pass a consent `setup` function. Function props can't cross the server-to-client boundary.
+*
+* @param options - The script tag options, plus the consent, route, and WebMCP settings for starting the scripts.
+* @returns Shopify's link and script tags, with the link tags first.
+* @publicDocs
+*/
 function ShopifyScripts(options) {
 	const { consent, navigate, routes, webMcp = true, ...scriptOptions } = options;
 	useEffect(() => {

package/dist/react/shopify-scripts.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"shopify-scripts.mjs","names":[],"sources":["../../src/react/shopify-scripts.tsx"],"sourcesContent":["\"use client\";\n\nimport { createElement, Fragment, useEffect } from \"react\";\nimport type * as React from \"react\";\n\nimport {\n  getShopifyScriptTags,\n  initializeShopifyScripts,\n  type ShopifyRoutesOptions,\n  type ShopifyScriptTagsOptions,\n} from \"../core/shopify-scripts\";\n\nexport type ShopifyScriptsProps = ShopifyScriptTagsOptions & {\n  navigate?: ShopifyRoutesOptions[\"navigate\"];\n  routes?: ShopifyRoutesOptions[\"routes\"];\n  webMcp?: boolean;\n};\n\ndeclare module \"react\" {\n  namespace JSX {\n    interface IntrinsicElements {\n      \"shopify-chat\": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;\n    }\n  }\n}\n\nexport function ShopifyScripts(options: ShopifyScriptsProps) {\n  const { consent, navigate, routes, webMcp = true, ...scriptOptions } = options;\n\n  useEffect(() => {\n    void initializeShopifyScripts({ consent, navigate, routes, webMcp });\n    // oxlint-disable-next-line react-hooks/exhaustive-deps -- ShopifyScripts browser startup is initialized once from initial props.\n  }, []);\n\n  return createElement(\n    Fragment,\n    null,\n    getShopifyScriptTags({ ...scriptOptions, consent }).tags.map(\n      ({ tagName, attributes, innerHTML }, index) =>\n        createElement(tagName, {\n          key: index,\n          ...getReactAttributes(attributes),\n          ...(innerHTML ? { dangerouslySetInnerHTML: { __html: innerHTML } } : {}),\n        }),\n    ),\n  );\n}\n\nfunction getReactAttributes(attributes: Record<string, string | boolean> = {}) {\n  const reactAttributes = Object.fromEntries(\n    Object.entries(attributes).map(([name, value]) => [\n      name === \"crossorigin\" ? \"crossOrigin\" : name,\n      value,\n    ]),\n  );\n\n  if (attributes.nonce !== undefined) {\n    // Browsers intentionally hide nonce content attributes from getAttribute(),\n    // which can make React report a false hydration mismatch for SSR scripts.\n    reactAttributes.suppressHydrationWarning = true;\n  }\n\n  if (attributes.async === true && typeof attributes.src === \"string\") {\n    // React hoists async scripts without handlers, which can let them execute before\n    // the inline Shopify bootstrap scripts that configure their globals.\n    return { ...reactAttributes, onLoad: disableReactScriptHoisting };\n  }\n\n  return reactAttributes;\n}\n\nconst disableReactScriptHoisting = () => {};\n"],"mappings":";;;;;;;AA0BA,SAAgB,eAAe,SAA8B;CAC3D,MAAM,EAAE,SAAS,UAAU,QAAQ,SAAS,MAAM,GAAG,kBAAkB;AAEvE,iBAAgB;AACd,EAAK,yBAAyB;GAAE;GAAS;GAAU;GAAQ;GAAQ,CAAC;IAEnE,EAAE,CAAC;AAEN,QAAO,cACL,UACA,MACA,qBAAqB;EAAE,GAAG;EAAe;EAAS,CAAC,CAAC,KAAK,KACtD,EAAE,SAAS,YAAY,aAAa,UACnC,cAAc,SAAS;EACrB,KAAK;EACL,GAAG,mBAAmB,WAAW;EACjC,GAAI,YAAY,EAAE,yBAAyB,EAAE,QAAQ,WAAW,EAAE,GAAG,EAAE;EACxE,CAAC,CACL,CACF;;AAGH,SAAS,mBAAmB,aAA+C,EAAE,EAAE;CAC7E,MAAM,kBAAkB,OAAO,YAC7B,OAAO,QAAQ,WAAW,CAAC,KAAK,CAAC,MAAM,WAAW,CAChD,SAAS,gBAAgB,gBAAgB,MACzC,MACD,CAAC,CACH;AAED,KAAI,WAAW,UAAU,OAGvB,iBAAgB,2BAA2B;AAG7C,KAAI,WAAW,UAAU,QAAQ,OAAO,WAAW,QAAQ,SAGzD,QAAO;EAAE,GAAG;EAAiB,QAAQ;EAA4B;AAGnE,QAAO;;AAGT,MAAM,mCAAmC"}
+{"version":3,"file":"shopify-scripts.mjs","names":[],"sources":["../../src/react/shopify-scripts.tsx"],"sourcesContent":["\"use client\";\n\nimport { createElement, Fragment, useEffect } from \"react\";\nimport type * as React from \"react\";\n\nimport {\n  getShopifyScriptTags,\n  initializeShopifyScripts,\n  type ShopifyRoutesOptions,\n  type ShopifyScriptTagsOptions,\n} from \"../core/shopify-scripts\";\n\n/**\n * Props for the `ShopifyScripts` component in React and Vue. The component renders Shopify's script\n * tags and starts the scripts in the browser after hydration. The component starts the scripts\n * once, with the first props. Later prop changes don't restart the scripts.\n *\n * In Next.js App Router, render the component from a client component when you pass a consent `setup` function. Function props can't cross the server-to-client boundary.\n *\n * @publicDocs\n */\nexport interface ShopifyScriptsProps extends ShopifyScriptTagsOptions {\n  /** Navigates after Shopify's scripts resolve a URL to your app's route. Defaults to a full page load. */\n  navigate?: ShopifyRoutesOptions[\"navigate\"];\n  /** Your app's custom route templates, which Shopify's scripts use to match storefront URLs. */\n  routes?: ShopifyRoutesOptions[\"routes\"];\n  /** Loads Shopify's WebMCP tools when the browser supports WebMCP. Defaults to `true`. */\n  webMcp?: boolean;\n}\n\ndeclare module \"react\" {\n  namespace JSX {\n    interface IntrinsicElements {\n      \"shopify-chat\": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;\n    }\n  }\n}\n\n/**\n * Renders Shopify's script tags and starts the scripts in the browser after hydration. The component starts the scripts once, with the first props. Later prop changes don't restart the scripts.\n *\n * `ShopifyScripts` is a client component. In Next.js App Router, render it from a client component when you pass a consent `setup` function. Function props can't cross the server-to-client boundary.\n *\n * @param options - The script tag options, plus the consent, route, and WebMCP settings for starting the scripts.\n * @returns Shopify's link and script tags, with the link tags first.\n * @publicDocs\n */\nexport function ShopifyScripts(options: ShopifyScriptsProps) {\n  const { consent, navigate, routes, webMcp = true, ...scriptOptions } = options;\n\n  useEffect(() => {\n    void initializeShopifyScripts({ consent, navigate, routes, webMcp });\n    // oxlint-disable-next-line react-hooks/exhaustive-deps -- ShopifyScripts browser startup is initialized once from initial props.\n  }, []);\n\n  return createElement(\n    Fragment,\n    null,\n    getShopifyScriptTags({ ...scriptOptions, consent }).tags.map(\n      ({ tagName, attributes, innerHTML }, index) =>\n        createElement(tagName, {\n          key: index,\n          ...getReactAttributes(attributes),\n          ...(innerHTML ? { dangerouslySetInnerHTML: { __html: innerHTML } } : {}),\n        }),\n    ),\n  );\n}\n\nfunction getReactAttributes(attributes: Record<string, string | boolean> = {}) {\n  const reactAttributes = Object.fromEntries(\n    Object.entries(attributes).map(([name, value]) => [\n      name === \"crossorigin\" ? \"crossOrigin\" : name,\n      value,\n    ]),\n  );\n\n  if (attributes.nonce !== undefined) {\n    // Browsers intentionally hide nonce content attributes from getAttribute(),\n    // which can make React report a false hydration mismatch for SSR scripts.\n    reactAttributes.suppressHydrationWarning = true;\n  }\n\n  if (attributes.async === true && typeof attributes.src === \"string\") {\n    // React hoists async scripts without handlers, which can let them execute before\n    // the inline Shopify bootstrap scripts that configure their globals.\n    return { ...reactAttributes, onLoad: disableReactScriptHoisting };\n  }\n\n  return reactAttributes;\n}\n\nconst disableReactScriptHoisting = () => {};\n"],"mappings":";;;;;;;;;;;;;;;;AA+CA,SAAgB,eAAe,SAA8B;CAC3D,MAAM,EAAE,SAAS,UAAU,QAAQ,SAAS,MAAM,GAAG,kBAAkB;AAEvE,iBAAgB;AACd,EAAK,yBAAyB;GAAE;GAAS;GAAU;GAAQ;GAAQ,CAAC;IAEnE,EAAE,CAAC;AAEN,QAAO,cACL,UACA,MACA,qBAAqB;EAAE,GAAG;EAAe;EAAS,CAAC,CAAC,KAAK,KACtD,EAAE,SAAS,YAAY,aAAa,UACnC,cAAc,SAAS;EACrB,KAAK;EACL,GAAG,mBAAmB,WAAW;EACjC,GAAI,YAAY,EAAE,yBAAyB,EAAE,QAAQ,WAAW,EAAE,GAAG,EAAE;EACxE,CAAC,CACL,CACF;;AAGH,SAAS,mBAAmB,aAA+C,EAAE,EAAE;CAC7E,MAAM,kBAAkB,OAAO,YAC7B,OAAO,QAAQ,WAAW,CAAC,KAAK,CAAC,MAAM,WAAW,CAChD,SAAS,gBAAgB,gBAAgB,MACzC,MACD,CAAC,CACH;AAED,KAAI,WAAW,UAAU,OAGvB,iBAAgB,2BAA2B;AAG7C,KAAI,WAAW,UAAU,QAAQ,OAAO,WAAW,QAAQ,SAGzD,QAAO;EAAE,GAAG;EAAiB,QAAQ;EAA4B;AAGnE,QAAO;;AAGT,MAAM,mCAAmC"}

package/dist/ts-plugin/index.cjs

@@ -53,6 +53,12 @@ function createGraphQLPluginConfig(schemaDirectory) {
 //#endregion
 //#region src/ts-plugin/index.ts
 const SCHEMA_DIRECTORY = (0, node_path.resolve)(__dirname, "..");
+/**
+* TypeScript language service plugin that configures gql.tada with Hydrogen's bundled Storefront and
+* Customer Account API schemas.
+*
+* @publicDocs
+*/
 const init = (modules) => {
 	const plugin = (0, gql_tada_ts_plugin.default)(modules);
 	return { create(info) {

package/dist/ts-plugin/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../src/graphql/plugin-config.ts","../../src/ts-plugin/index.ts"],"sourcesContent":["import { join } from \"node:path\";\n\nconst STOREFRONT_SCHEMA_FILE_NAME = \"storefront.schema.json\";\nconst CUSTOMER_ACCOUNT_SCHEMA_FILE_NAME = \"customer-account.schema.json\";\nconst STOREFRONT_OUTPUT_FILE_NAME = \"storefront-graphql-env.d.ts\";\nconst CUSTOMER_ACCOUNT_OUTPUT_FILE_NAME = \"customer-account-graphql-env.d.ts\";\n\nexport function createGraphQLPluginConfig(schemaDirectory: string) {\n  return {\n    name: \"gql.tada/ts-plugin\",\n    schemas: [\n      {\n        name: \"storefront\",\n        schema: join(schemaDirectory, STOREFRONT_SCHEMA_FILE_NAME),\n        tadaOutputLocation: STOREFRONT_OUTPUT_FILE_NAME,\n      },\n      {\n        name: \"customer-account\",\n        schema: join(schemaDirectory, CUSTOMER_ACCOUNT_SCHEMA_FILE_NAME),\n        tadaOutputLocation: CUSTOMER_ACCOUNT_OUTPUT_FILE_NAME,\n      },\n    ],\n    trackFieldUsage: false,\n  } as const;\n}\n","import { resolve } from \"node:path\";\n\nimport gqlTadaPlugin from \"gql.tada/ts-plugin\";\nimport type ts from \"typescript/lib/tsserverlibrary\";\n\nimport { createGraphQLPluginConfig } from \"../graphql/plugin-config\";\n\nconst SCHEMA_DIRECTORY = resolve(__dirname, \"..\");\n\nconst init: ts.server.PluginModuleFactory = (modules) => {\n  const plugin = gqlTadaPlugin(modules);\n\n  return {\n    create(info) {\n      return plugin.create({\n        ...info,\n        config: createGraphQLPluginConfig(SCHEMA_DIRECTORY),\n      });\n    },\n  };\n};\n\nexport default init;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEA,MAAM,8BAA8B;AACpC,MAAM,oCAAoC;AAC1C,MAAM,8BAA8B;AACpC,MAAM,oCAAoC;AAE1C,SAAgB,0BAA0B,iBAAyB;AACjE,QAAO;EACL,MAAM;EACN,SAAS,CACP;GACE,MAAM;GACN,4BAAa,iBAAiB,4BAA4B;GAC1D,oBAAoB;GACrB,EACD;GACE,MAAM;GACN,4BAAa,iBAAiB,kCAAkC;GAChE,oBAAoB;GACrB,CACF;EACD,iBAAiB;EAClB;;;;;AChBH,MAAM,0CAA2B,WAAW,KAAK;AAEjD,MAAM,QAAuC,YAAY;CACvD,MAAM,yCAAuB,QAAQ;AAErC,QAAO,EACL,OAAO,MAAM;AACX,SAAO,OAAO,OAAO;GACnB,GAAG;GACH,QAAQ,0BAA0B,iBAAiB;GACpD,CAAC;IAEL"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/graphql/plugin-config.ts","../../src/ts-plugin/index.ts"],"sourcesContent":["import { join } from \"node:path\";\n\nconst STOREFRONT_SCHEMA_FILE_NAME = \"storefront.schema.json\";\nconst CUSTOMER_ACCOUNT_SCHEMA_FILE_NAME = \"customer-account.schema.json\";\nconst STOREFRONT_OUTPUT_FILE_NAME = \"storefront-graphql-env.d.ts\";\nconst CUSTOMER_ACCOUNT_OUTPUT_FILE_NAME = \"customer-account-graphql-env.d.ts\";\n\nexport function createGraphQLPluginConfig(schemaDirectory: string) {\n  return {\n    name: \"gql.tada/ts-plugin\",\n    schemas: [\n      {\n        name: \"storefront\",\n        schema: join(schemaDirectory, STOREFRONT_SCHEMA_FILE_NAME),\n        tadaOutputLocation: STOREFRONT_OUTPUT_FILE_NAME,\n      },\n      {\n        name: \"customer-account\",\n        schema: join(schemaDirectory, CUSTOMER_ACCOUNT_SCHEMA_FILE_NAME),\n        tadaOutputLocation: CUSTOMER_ACCOUNT_OUTPUT_FILE_NAME,\n      },\n    ],\n    trackFieldUsage: false,\n  } as const;\n}\n","import { resolve } from \"node:path\";\n\nimport gqlTadaPlugin from \"gql.tada/ts-plugin\";\nimport type ts from \"typescript/lib/tsserverlibrary\";\n\nimport { createGraphQLPluginConfig } from \"../graphql/plugin-config\";\n\nconst SCHEMA_DIRECTORY = resolve(__dirname, \"..\");\n\n/**\n * TypeScript language service plugin that configures gql.tada with Hydrogen's bundled Storefront and\n * Customer Account API schemas.\n *\n * @publicDocs\n */\nconst init: ts.server.PluginModuleFactory = (modules) => {\n  const plugin = gqlTadaPlugin(modules);\n\n  return {\n    create(info) {\n      return plugin.create({\n        ...info,\n        config: createGraphQLPluginConfig(SCHEMA_DIRECTORY),\n      });\n    },\n  };\n};\n\nexport default init;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEA,MAAM,8BAA8B;AACpC,MAAM,oCAAoC;AAC1C,MAAM,8BAA8B;AACpC,MAAM,oCAAoC;AAE1C,SAAgB,0BAA0B,iBAAyB;AACjE,QAAO;EACL,MAAM;EACN,SAAS,CACP;GACE,MAAM;GACN,4BAAa,iBAAiB,4BAA4B;GAC1D,oBAAoB;GACrB,EACD;GACE,MAAM;GACN,4BAAa,iBAAiB,kCAAkC;GAChE,oBAAoB;GACrB,CACF;EACD,iBAAiB;EAClB;;;;;AChBH,MAAM,0CAA2B,WAAW,KAAK;;;;;;;AAQjD,MAAM,QAAuC,YAAY;CACvD,MAAM,yCAAuB,QAAQ;AAErC,QAAO,EACL,OAAO,MAAM;AACX,SAAO,OAAO,OAAO;GACnB,GAAG;GACH,QAAQ,0BAA0B,iBAAiB;GACpD,CAAC;IAEL"}

package/dist/ts-plugin/index.d.cts

@@ -1,4 +1,10 @@
 import ts = require("typescript/lib/tsserverlibrary");
 
+/**
+ * TypeScript language service plugin that configures gql.tada with Hydrogen's bundled Storefront and
+ * Customer Account API schemas.
+ *
+ * @publicDocs
+ */
 declare const init: ts.server.PluginModuleFactory;
 export = init;

package/dist/vite/local-https.d.mts

@@ -1,41 +1,75 @@
 import { Plugin } from "vite";
 
 //#region src/vite/local-https.d.ts
+/**
+ * Default host, `local.tryhydrogen.dev`, and port, `5173`, for local HTTPS. Pass the values to frameworks that set their own dev server host and port, such as Astro.
+ *
+ * @publicDocs
+ */
 declare const LOCAL_HTTPS_DEFAULTS: {
   readonly host: "local.tryhydrogen.dev";
   readonly port: 5173;
 };
-/** Options for Hydrogen's local HTTPS Vite plugin. */
+/** Switch, host, port, and certificate files for local HTTPS. */
 type LocalHttpsOptions = {
-  /** Enable trusted local HTTPS for the dev server. */enabled: boolean; /** Local hostname registered in Shopify admin. Defaults to `local.tryhydrogen.dev`. */
-  host?: string; /** Local port registered in Shopify admin. Defaults to `5173`. */
-  port?: number; /** Certificate file path. Defaults to Hydrogen's mkcert path under `~/.shopify/hydrogen/certs`. */
-  certPath?: string | URL; /** Private key file path. Defaults to Hydrogen's mkcert path under `~/.shopify/hydrogen/certs`. */
+  /** Turns on local HTTPS for the dev server. When `false`, the plugin leaves the Vite config unchanged. */enabled: boolean; /** Hostname for the dev server and the Customer Account API URLs. Defaults to `local.tryhydrogen.dev`. */
+  host?: string; /** Port for the dev server. Vite exits when another process uses the port. Defaults to `5173`. */
+  port?: number; /** Path to the certificate file. Defaults to `~/.shopify/hydrogen/certs/<host>.pem`. A leading `~/` points to your home directory, and a relative path starts from the current working directory. */
+  certPath?: string | URL; /** Path to the private key file. Defaults to `~/.shopify/hydrogen/certs/<host>-key.pem`. Accepts the same path forms as `certPath`. */
   keyPath?: string | URL;
 };
-type LocalHttpsPlugin = Plugin & {
-  api: {
-    /** Returns host, port, and TLS file paths for frameworks that terminate HTTPS outside Vite. */getDevServerConfig(): LocalHttpsDevServerConfig | undefined;
-  };
-};
+/** The local HTTPS Vite plugin, with an API for frameworks that start their own HTTPS server. */
+type LocalHttpsPlugin = Plugin & LocalHttpsPluginExtension;
+/** The API that the local HTTPS Vite plugin adds to the Vite plugin object. */
+interface LocalHttpsPluginExtension {
+  /** Methods for frameworks that start their own HTTPS server. */
+  api: LocalHttpsPluginApi;
+}
+/** Methods for frameworks that start their own HTTPS server. */
+interface LocalHttpsPluginApi {
+  /**
+   * Returns the host, port, and certificate paths for frameworks that serve HTTPS outside Vite, such as Nuxt.
+   *
+   * Returns `undefined` when `enabled` is `false` or a certificate file is missing.
+   */
+  getDevServerConfig(): LocalHttpsDevServerConfig | undefined;
+}
+/** Host, port, and certificate file paths for serving local HTTPS outside Vite. */
 type LocalHttpsDevServerConfig = {
-  host: string;
-  port: number;
+  /** Local hostname that the dev server serves, such as `local.tryhydrogen.dev`. */host: string; /** Port for the dev server. */
+  port: number; /** Absolute paths to the certificate file and the private key file. */
   https: {
     cert: string;
     key: string;
   };
 };
 /**
- * Configures Vite for trusted local HTTPS on Hydrogen's default development host.
+ * Serves your Vite dev server over trusted HTTPS on a fixed host and port, and adds the dev server URLs to your Customer Account API settings.
+ * Vite exits when another process uses the port. The dev server speaks HTTP/1.1 only.
+ *
+ * When `vite dev` starts without certificate files, the plugin asks for permission in the terminal, then creates the files. The plugin skips the prompt without an interactive terminal and in CI. Hydrogen treats any `CI` environment variable value other than an empty string, `false`, or `0` as CI. While certificate files are missing, the plugin prints a warning and leaves HTTPS off.
+ *
+ * After the dev server starts, the plugin runs Shopify CLI to update your Customer Account API settings with the dev server URLs. The update needs a Shopify CLI that includes `@shopify/cli-hydrogen` 13.0.4 or later. When the project has no linked Hydrogen storefront, Shopify CLI asks you to link one first. When Shopify CLI is missing or outdated, or the update fails, the plugin prints the URLs to enter by hand and the dev server keeps running. In CI, the plugin prints the URLs and skips Shopify CLI.
+ *
+ * @param options Switch, host, port, and certificate paths for local HTTPS.
+ * @returns A Vite plugin. Its `api.getDevServerConfig()` method returns the HTTPS settings for frameworks that serve HTTPS outside Vite.
+ * @publicDocs
  */
 declare function localHttps(options: LocalHttpsOptions): LocalHttpsPlugin;
+/** Host and certificate paths for provisionLocalHttps. */
 type ProvisionLocalHttpsOptions = Omit<LocalHttpsOptions, "enabled" | "port">;
 /**
- * Downloads a pinned, checksum-verified mkcert release and generates the
- * trusted local certificate files when they do not exist yet. The Vite plugin
- * runs this automatically on `vite dev`; call it directly for frameworks that
- * read certificate paths before Vite starts or from setup scripts.
+ * Creates trusted certificate files for local HTTPS. Call the function from a setup script, or
+ * before you start a framework that reads certificate paths when its config loads, such as Nuxt.
+ *
+ * When both files exist, the function returns their paths and changes nothing. Otherwise, the
+ * function downloads a pinned, checksum-verified mkcert release, adds the mkcert certificate
+ * authority to your system trust store, and creates the certificate and private key. mkcert can
+ * ask for your password.
+ *
+ * @param options Host and certificate paths. Each option has a Hydrogen default.
+ * @returns The host and the absolute paths to the certificate and the private key.
+ * @publicDocs
  */
 declare function provisionLocalHttps(options?: ProvisionLocalHttpsOptions): Promise<{
   host: string;

package/dist/vite/local-https.mjs

@@ -7,6 +7,11 @@ import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 //#region src/vite/local-https.ts
+/**
+* Default host, `local.tryhydrogen.dev`, and port, `5173`, for local HTTPS. Pass the values to frameworks that set their own dev server host and port, such as Astro.
+*
+* @publicDocs
+*/
 const LOCAL_HTTPS_DEFAULTS = {
 	host: "local.tryhydrogen.dev",
 	port: 5173
@@ -25,7 +30,16 @@ const HTTP1_ONLY_RESPONSE_HEADERS = new Set([
 const emittedMissingCertificateWarnings = /* @__PURE__ */ new Set();
 const startedCustomerAccountSetups = /* @__PURE__ */ new Set();
 /**
-* Configures Vite for trusted local HTTPS on Hydrogen's default development host.
+* Serves your Vite dev server over trusted HTTPS on a fixed host and port, and adds the dev server URLs to your Customer Account API settings.
+* Vite exits when another process uses the port. The dev server speaks HTTP/1.1 only.
+*
+* When `vite dev` starts without certificate files, the plugin asks for permission in the terminal, then creates the files. The plugin skips the prompt without an interactive terminal and in CI. Hydrogen treats any `CI` environment variable value other than an empty string, `false`, or `0` as CI. While certificate files are missing, the plugin prints a warning and leaves HTTPS off.
+*
+* After the dev server starts, the plugin runs Shopify CLI to update your Customer Account API settings with the dev server URLs. The update needs a Shopify CLI that includes `@shopify/cli-hydrogen` 13.0.4 or later. When the project has no linked Hydrogen storefront, Shopify CLI asks you to link one first. When Shopify CLI is missing or outdated, or the update fails, the plugin prints the URLs to enter by hand and the dev server keeps running. In CI, the plugin prints the URLs and skips Shopify CLI.
+*
+* @param options Switch, host, port, and certificate paths for local HTTPS.
+* @returns A Vite plugin. Its `api.getDevServerConfig()` method returns the HTTPS settings for frameworks that serve HTTPS outside Vite.
+* @publicDocs
 */
 function localHttps(options) {
 	const settings = options.enabled ? resolveLocalHttpsSettings(options) : void 0;
@@ -80,10 +94,17 @@ function localHttps(options) {
 	};
 }
 /**
-* Downloads a pinned, checksum-verified mkcert release and generates the
-* trusted local certificate files when they do not exist yet. The Vite plugin
-* runs this automatically on `vite dev`; call it directly for frameworks that
-* read certificate paths before Vite starts or from setup scripts.
+* Creates trusted certificate files for local HTTPS. Call the function from a setup script, or
+* before you start a framework that reads certificate paths when its config loads, such as Nuxt.
+*
+* When both files exist, the function returns their paths and changes nothing. Otherwise, the
+* function downloads a pinned, checksum-verified mkcert release, adds the mkcert certificate
+* authority to your system trust store, and creates the certificate and private key. mkcert can
+* ask for your password.
+*
+* @param options Host and certificate paths. Each option has a Hydrogen default.
+* @returns The host and the absolute paths to the certificate and the private key.
+* @publicDocs
 */
 async function provisionLocalHttps(options = {}) {
 	const settings = resolveLocalHttpsSettings({

package/dist/vite/local-https.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"local-https.mjs","names":[],"sources":["../../src/vite/local-https.ts"],"sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport type { OutgoingHttpHeader, OutgoingHttpHeaders, ServerResponse } from \"node:http\";\nimport { homedir } from \"node:os\";\nimport { dirname, isAbsolute, join, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nimport type { ConfigEnv, Plugin, ViteDevServer } from \"vite\";\n\nimport { confirmCertificateInstallation } from \"./certificate-prompt\";\nimport {\n  configureCustomerAccountUrls,\n  isContinuousIntegration,\n  resolveCustomerAccountUrls,\n} from \"./customer-account\";\nimport { provisionCertificates } from \"./mkcert\";\n\nexport const LOCAL_HTTPS_DEFAULTS = {\n  host: \"local.tryhydrogen.dev\",\n  port: 5_173,\n} as const;\n\nconst HEADER_PAIR_SIZE = 2;\nconst HTTP1_ONLY_RESPONSE_HEADERS = new Set([\n  \"connection\",\n  \"keep-alive\",\n  \"proxy-authenticate\",\n  \"proxy-authorization\",\n  \"te\",\n  \"trailer\",\n  \"transfer-encoding\",\n  \"upgrade\",\n]);\nconst emittedMissingCertificateWarnings = new Set<string>();\nconst startedCustomerAccountSetups = new Set<string>();\n\n/** Options for Hydrogen's local HTTPS Vite plugin. */\nexport type LocalHttpsOptions = {\n  /** Enable trusted local HTTPS for the dev server. */\n  enabled: boolean;\n  /** Local hostname registered in Shopify admin. Defaults to `local.tryhydrogen.dev`. */\n  host?: string;\n  /** Local port registered in Shopify admin. Defaults to `5173`. */\n  port?: number;\n  /** Certificate file path. Defaults to Hydrogen's mkcert path under `~/.shopify/hydrogen/certs`. */\n  certPath?: string | URL;\n  /** Private key file path. Defaults to Hydrogen's mkcert path under `~/.shopify/hydrogen/certs`. */\n  keyPath?: string | URL;\n};\n\nexport type LocalHttpsPlugin = Plugin & {\n  api: {\n    /** Returns host, port, and TLS file paths for frameworks that terminate HTTPS outside Vite. */\n    getDevServerConfig(): LocalHttpsDevServerConfig | undefined;\n  };\n};\n\nexport type LocalHttpsDevServerConfig = {\n  host: string;\n  port: number;\n  https: {\n    cert: string;\n    key: string;\n  };\n};\n\n/**\n * Configures Vite for trusted local HTTPS on Hydrogen's default development host.\n */\nexport function localHttps(options: LocalHttpsOptions): LocalHttpsPlugin {\n  const settings = options.enabled ? resolveLocalHttpsSettings(options) : undefined;\n  let certificateFiles: LocalHttpsCertificateFiles | undefined;\n\n  const getCertificateFiles = () => {\n    if (!settings) return;\n\n    certificateFiles ??= readCertificateFiles(settings);\n    return certificateFiles;\n  };\n\n  const getDevServerConfig = () => {\n    if (!settings || !checkCertificateFiles(settings)) return;\n\n    getCertificateFiles();\n\n    return {\n      host: settings.host,\n      port: settings.port,\n      https: {\n        cert: settings.certPath,\n        key: settings.keyPath,\n      },\n    };\n  };\n\n  return {\n    name: \"hydrogen-local-https\",\n    api: { getDevServerConfig },\n    async config(_config: unknown, env: ConfigEnv) {\n      if (settings && env.command === \"serve\" && !env.isPreview) {\n        const certificatesAvailable = await ensureCertificateFiles(settings);\n        if (!certificatesAvailable) return;\n      } else if (settings && !checkCertificateFiles(settings)) {\n        return;\n      }\n\n      const certificates = getCertificateFiles();\n      if (!settings || !certificates) return;\n\n      return {\n        server: {\n          allowedHosts: [settings.host],\n          host: settings.host,\n          port: settings.port,\n          strictPort: true,\n          https: {\n            // Several framework dev servers fail when Vite negotiates HTTP/2.\n            ALPNProtocols: [\"http/1.1\"],\n            cert: certificates.cert,\n            key: certificates.key,\n          },\n          hmr: {\n            host: settings.host,\n            protocol: \"wss\",\n          },\n        },\n      };\n    },\n    configureServer(server) {\n      if (!settings || !checkCertificateFiles(settings)) return;\n\n      getCertificateFiles();\n      configureLocalHttpsServer(server, settings);\n    },\n  };\n}\n\nexport type ProvisionLocalHttpsOptions = Omit<LocalHttpsOptions, \"enabled\" | \"port\">;\n\n/**\n * Downloads a pinned, checksum-verified mkcert release and generates the\n * trusted local certificate files when they do not exist yet. The Vite plugin\n * runs this automatically on `vite dev`; call it directly for frameworks that\n * read certificate paths before Vite starts or from setup scripts.\n */\nexport async function provisionLocalHttps(options: ProvisionLocalHttpsOptions = {}) {\n  const settings = resolveLocalHttpsSettings({ enabled: true, ...options });\n\n  if (!certificateFilesExist(settings)) {\n    await provisionCertificates(settings);\n  }\n\n  return {\n    host: settings.host,\n    certPath: settings.certPath,\n    keyPath: settings.keyPath,\n  };\n}\n\ntype LocalHttpsSettings = {\n  host: string;\n  port: number;\n  certPath: string;\n  keyPath: string;\n};\n\ntype LocalHttpsCertificateFiles = {\n  cert: Buffer;\n  key: Buffer;\n};\n\nfunction resolveLocalHttpsSettings(options: LocalHttpsOptions): LocalHttpsSettings {\n  const host = options.host ?? LOCAL_HTTPS_DEFAULTS.host;\n  const certificateDirectory = join(homedir(), \".shopify\", \"hydrogen\", \"certs\");\n\n  return {\n    host,\n    port: options.port ?? LOCAL_HTTPS_DEFAULTS.port,\n    certPath: resolveCertificatePath(options.certPath ?? join(certificateDirectory, `${host}.pem`)),\n    keyPath: resolveCertificatePath(\n      options.keyPath ?? join(certificateDirectory, `${host}-key.pem`),\n    ),\n  };\n}\n\nfunction resolveCertificatePath(path: string | URL) {\n  if (path instanceof URL) return fileURLToPath(path);\n  if (path === \"~\") return homedir();\n  if (path.startsWith(\"~/\")) return resolve(homedir(), path.slice(2));\n  return isAbsolute(path) ? path : resolve(path);\n}\n\nfunction certificateFilesExist(settings: LocalHttpsSettings) {\n  return existsSync(settings.certPath) && existsSync(settings.keyPath);\n}\n\nasync function ensureCertificateFiles(settings: LocalHttpsSettings): Promise<boolean> {\n  if (certificateFilesExist(settings)) return true;\n\n  // Installing the mkcert certificate authority needs an interactive trust\n  // prompt on first run, which hangs or fails on CI runners.\n  if (isContinuousIntegration()) {\n    return checkCertificateFiles(\n      settings,\n      \"Automatic certificate provisioning is skipped in CI environments (the CI environment variable is set).\",\n    );\n  }\n\n  if (!(await confirmCertificateInstallation(settings.host))) {\n    return checkCertificateFiles(\n      settings,\n      \"Automatic certificate provisioning requires confirmation in an interactive terminal.\",\n    );\n  }\n\n  try {\n    await provisionCertificates(settings);\n    return true;\n  } catch (error) {\n    return checkCertificateFiles(\n      settings,\n      `Automatic certificate provisioning failed:\\n  ${error instanceof Error ? error.message : String(error)}`,\n    );\n  }\n}\n\nfunction checkCertificateFiles(settings: LocalHttpsSettings, provisioningNote?: string) {\n  const missingPaths = [settings.certPath, settings.keyPath].filter((path) => !existsSync(path));\n  if (missingPaths.length === 0) return true;\n\n  const warning = formatMissingCertificateWarning(settings, missingPaths, provisioningNote);\n  if (!emittedMissingCertificateWarnings.has(warning)) {\n    emittedMissingCertificateWarnings.add(warning);\n    process.emitWarning(warning, { type: \"HydrogenLocalHttpsWarning\" });\n  }\n  return false;\n}\n\nfunction formatMissingCertificateWarning(\n  { certPath, host, keyPath }: LocalHttpsSettings,\n  missingPaths: string[],\n  provisioningNote?: string,\n) {\n  const certificateDirectories = [...new Set([dirname(certPath), dirname(keyPath)])];\n  const provisioningFailure = provisioningNote === undefined ? [] : [\"\", provisioningNote];\n\n  return [\n    \"Local HTTPS is disabled because certificate files are missing:\",\n    ...missingPaths.map((path) => `  ${path}`),\n    ...provisioningFailure,\n    \"\",\n    \"Expected certificate files:\",\n    `  Certificate: ${certPath}`,\n    `  Private key: ${keyPath}`,\n    \"\",\n    \"Run the automatic setup:\",\n    \"  npx hydrogen certs install\",\n    \"\",\n    \"Or install and configure mkcert, then generate the certificate:\",\n    \"  macOS: brew install mkcert\",\n    \"  mkcert -install\",\n    `  mkdir -p ${certificateDirectories.map(shellQuote).join(\" \")}`,\n    `  mkcert -cert-file ${shellQuote(certPath)} -key-file ${shellQuote(keyPath)} ${shellQuote(host)}`,\n  ].join(\"\\n\");\n}\n\nfunction readCertificateFiles(settings: LocalHttpsSettings): LocalHttpsCertificateFiles {\n  return {\n    cert: readCertificateFile(settings, \"certificate\", settings.certPath),\n    key: readCertificateFile(settings, \"private key\", settings.keyPath),\n  };\n}\n\nfunction readCertificateFile(settings: LocalHttpsSettings, label: string, path: string) {\n  try {\n    return readFileSync(path);\n  } catch (error) {\n    throw new Error(formatCertificateReadError(settings, label, path, error), { cause: error });\n  }\n}\n\nfunction formatCertificateReadError(\n  { certPath, host, keyPath }: LocalHttpsSettings,\n  label: string,\n  path: string,\n  error: unknown,\n) {\n  const certificateDirectories = [...new Set([dirname(certPath), dirname(keyPath)])];\n  const reason = error instanceof Error ? error.message : String(error);\n\n  return [\n    `Local HTTPS requires a readable ${label} file:`,\n    `  ${path}`,\n    `Reason: ${reason}`,\n    \"\",\n    \"Expected certificate files:\",\n    `  Certificate: ${certPath}`,\n    `  Private key: ${keyPath}`,\n    \"\",\n    \"Install and configure mkcert, then generate the certificate:\",\n    \"  macOS: brew install mkcert\",\n    \"  mkcert -install\",\n    `  mkdir -p ${certificateDirectories.map(shellQuote).join(\" \")}`,\n    `  mkcert -cert-file ${shellQuote(certPath)} -key-file ${shellQuote(keyPath)} ${shellQuote(host)}`,\n  ].join(\"\\n\");\n}\n\nfunction shellQuote(value: string) {\n  return `'${value.replaceAll(\"'\", `'\\\\''`)}'`;\n}\n\nfunction configureLocalHttpsServer(server: ViteDevServer, settings: LocalHttpsSettings) {\n  // The configured port is only a fallback: frameworks that own the listener\n  // (or auto-incremented ports) can bind somewhere else, and the Customer\n  // Account URLs registered in admin must match the port actually served.\n  const resolveBoundPort = () => {\n    const address = server.httpServer?.address();\n    return address && typeof address === \"object\" ? address.port : settings.port;\n  };\n\n  server.middlewares.use((request, response, next) => {\n    request.headers[\"x-forwarded-host\"] ??=\n      request.headers.host ?? `${settings.host}:${resolveBoundPort()}`;\n    request.headers[\"x-forwarded-proto\"] ??= \"https\";\n    stripHttp1OnlyResponseHeaders(response);\n    next();\n  });\n\n  const configureCustomerAccounts = () => {\n    const port = resolveBoundPort();\n    const settingsKey = `${server.config.root}:${settings.host}:${port}`;\n    if (startedCustomerAccountSetups.has(settingsKey)) return;\n    startedCustomerAccountSetups.add(settingsKey);\n\n    void configureCustomerAccountUrls({\n      logger: server.config.logger,\n      root: server.config.root,\n      urls: resolveCustomerAccountUrls(settings.host, port),\n    });\n  };\n\n  if (server.httpServer) {\n    server.httpServer.once(\"listening\", configureCustomerAccounts);\n  } else {\n    configureCustomerAccounts();\n  }\n}\n\nfunction stripHttp1OnlyResponseHeaders(response: ServerResponse) {\n  const originalWriteHead = response.writeHead.bind(response);\n\n  response.writeHead = (\n    statusCode: number,\n    statusMessageOrHeaders?: string | OutgoingHttpHeaders | OutgoingHttpHeader[],\n    headers?: OutgoingHttpHeaders | OutgoingHttpHeader[],\n  ) => {\n    removeStoredHttp1OnlyHeaders(response);\n\n    if (typeof statusMessageOrHeaders === \"string\") {\n      return originalWriteHead(\n        statusCode,\n        statusMessageOrHeaders,\n        sanitizeWriteHeadHeaders(headers),\n      );\n    }\n\n    return originalWriteHead(statusCode, sanitizeWriteHeadHeaders(statusMessageOrHeaders));\n  };\n}\n\nfunction removeStoredHttp1OnlyHeaders(response: ServerResponse) {\n  for (const header of HTTP1_ONLY_RESPONSE_HEADERS) {\n    response.removeHeader(header);\n  }\n}\n\nfunction sanitizeWriteHeadHeaders(headers: OutgoingHttpHeaders | OutgoingHttpHeader[] | undefined) {\n  if (Array.isArray(headers)) return sanitizeHeaderArray(headers);\n  if (headers) return sanitizeHeaderObject(headers);\n  return headers;\n}\n\nfunction sanitizeHeaderObject(headers: OutgoingHttpHeaders) {\n  const sanitizedHeaders: OutgoingHttpHeaders = {};\n\n  for (const [name, value] of Object.entries(headers)) {\n    if (!isHttp1OnlyHeader(name)) sanitizedHeaders[name] = value;\n  }\n\n  return sanitizedHeaders;\n}\n\nfunction sanitizeHeaderArray(headers: OutgoingHttpHeader[]) {\n  const sanitizedHeaders: OutgoingHttpHeader[] = [];\n\n  for (let index = 0; index < headers.length; index += HEADER_PAIR_SIZE) {\n    const name = headers[index];\n    const value = headers[index + 1];\n    if (typeof name === \"string\" && isHttp1OnlyHeader(name)) continue;\n\n    sanitizedHeaders.push(name);\n    if (value !== undefined) sanitizedHeaders.push(value);\n  }\n\n  return sanitizedHeaders;\n}\n\nfunction isHttp1OnlyHeader(name: string) {\n  return HTTP1_ONLY_RESPONSE_HEADERS.has(name.toLowerCase());\n}\n"],"mappings":"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"}
+{"version":3,"file":"local-https.mjs","names":[],"sources":["../../src/vite/local-https.ts"],"sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport type { OutgoingHttpHeader, OutgoingHttpHeaders, ServerResponse } from \"node:http\";\nimport { homedir } from \"node:os\";\nimport { dirname, isAbsolute, join, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nimport type { ConfigEnv, Plugin, ViteDevServer } from \"vite\";\n\nimport { confirmCertificateInstallation } from \"./certificate-prompt\";\nimport {\n  configureCustomerAccountUrls,\n  isContinuousIntegration,\n  resolveCustomerAccountUrls,\n} from \"./customer-account\";\nimport { provisionCertificates } from \"./mkcert\";\n\n/**\n * Default host, `local.tryhydrogen.dev`, and port, `5173`, for local HTTPS. Pass the values to frameworks that set their own dev server host and port, such as Astro.\n *\n * @publicDocs\n */\nexport const LOCAL_HTTPS_DEFAULTS = {\n  host: \"local.tryhydrogen.dev\",\n  port: 5_173,\n} as const;\n\nconst HEADER_PAIR_SIZE = 2;\nconst HTTP1_ONLY_RESPONSE_HEADERS = new Set([\n  \"connection\",\n  \"keep-alive\",\n  \"proxy-authenticate\",\n  \"proxy-authorization\",\n  \"te\",\n  \"trailer\",\n  \"transfer-encoding\",\n  \"upgrade\",\n]);\nconst emittedMissingCertificateWarnings = new Set<string>();\nconst startedCustomerAccountSetups = new Set<string>();\n\n/** Switch, host, port, and certificate files for local HTTPS. */\nexport type LocalHttpsOptions = {\n  /** Turns on local HTTPS for the dev server. When `false`, the plugin leaves the Vite config unchanged. */\n  enabled: boolean;\n  /** Hostname for the dev server and the Customer Account API URLs. Defaults to `local.tryhydrogen.dev`. */\n  host?: string;\n  /** Port for the dev server. Vite exits when another process uses the port. Defaults to `5173`. */\n  port?: number;\n  /** Path to the certificate file. Defaults to `~/.shopify/hydrogen/certs/<host>.pem`. A leading `~/` points to your home directory, and a relative path starts from the current working directory. */\n  certPath?: string | URL;\n  /** Path to the private key file. Defaults to `~/.shopify/hydrogen/certs/<host>-key.pem`. Accepts the same path forms as `certPath`. */\n  keyPath?: string | URL;\n};\n\n/** The local HTTPS Vite plugin, with an API for frameworks that start their own HTTPS server. */\nexport type LocalHttpsPlugin = Plugin & LocalHttpsPluginExtension;\n\n/** The API that the local HTTPS Vite plugin adds to the Vite plugin object. */\ninterface LocalHttpsPluginExtension {\n  /** Methods for frameworks that start their own HTTPS server. */\n  api: LocalHttpsPluginApi;\n}\n\n/** Methods for frameworks that start their own HTTPS server. */\ninterface LocalHttpsPluginApi {\n  /**\n   * Returns the host, port, and certificate paths for frameworks that serve HTTPS outside Vite, such as Nuxt.\n   *\n   * Returns `undefined` when `enabled` is `false` or a certificate file is missing.\n   */\n  getDevServerConfig(): LocalHttpsDevServerConfig | undefined;\n}\n\n/** Host, port, and certificate file paths for serving local HTTPS outside Vite. */\nexport type LocalHttpsDevServerConfig = {\n  /** Local hostname that the dev server serves, such as `local.tryhydrogen.dev`. */\n  host: string;\n  /** Port for the dev server. */\n  port: number;\n  /** Absolute paths to the certificate file and the private key file. */\n  https: {\n    cert: string;\n    key: string;\n  };\n};\n\n/**\n * Serves your Vite dev server over trusted HTTPS on a fixed host and port, and adds the dev server URLs to your Customer Account API settings.\n * Vite exits when another process uses the port. The dev server speaks HTTP/1.1 only.\n *\n * When `vite dev` starts without certificate files, the plugin asks for permission in the terminal, then creates the files. The plugin skips the prompt without an interactive terminal and in CI. Hydrogen treats any `CI` environment variable value other than an empty string, `false`, or `0` as CI. While certificate files are missing, the plugin prints a warning and leaves HTTPS off.\n *\n * After the dev server starts, the plugin runs Shopify CLI to update your Customer Account API settings with the dev server URLs. The update needs a Shopify CLI that includes `@shopify/cli-hydrogen` 13.0.4 or later. When the project has no linked Hydrogen storefront, Shopify CLI asks you to link one first. When Shopify CLI is missing or outdated, or the update fails, the plugin prints the URLs to enter by hand and the dev server keeps running. In CI, the plugin prints the URLs and skips Shopify CLI.\n *\n * @param options Switch, host, port, and certificate paths for local HTTPS.\n * @returns A Vite plugin. Its `api.getDevServerConfig()` method returns the HTTPS settings for frameworks that serve HTTPS outside Vite.\n * @publicDocs\n */\nexport function localHttps(options: LocalHttpsOptions): LocalHttpsPlugin {\n  const settings = options.enabled ? resolveLocalHttpsSettings(options) : undefined;\n  let certificateFiles: LocalHttpsCertificateFiles | undefined;\n\n  const getCertificateFiles = () => {\n    if (!settings) return;\n\n    certificateFiles ??= readCertificateFiles(settings);\n    return certificateFiles;\n  };\n\n  const getDevServerConfig = () => {\n    if (!settings || !checkCertificateFiles(settings)) return;\n\n    getCertificateFiles();\n\n    return {\n      host: settings.host,\n      port: settings.port,\n      https: {\n        cert: settings.certPath,\n        key: settings.keyPath,\n      },\n    };\n  };\n\n  return {\n    name: \"hydrogen-local-https\",\n    api: { getDevServerConfig },\n    async config(_config: unknown, env: ConfigEnv) {\n      if (settings && env.command === \"serve\" && !env.isPreview) {\n        const certificatesAvailable = await ensureCertificateFiles(settings);\n        if (!certificatesAvailable) return;\n      } else if (settings && !checkCertificateFiles(settings)) {\n        return;\n      }\n\n      const certificates = getCertificateFiles();\n      if (!settings || !certificates) return;\n\n      return {\n        server: {\n          allowedHosts: [settings.host],\n          host: settings.host,\n          port: settings.port,\n          strictPort: true,\n          https: {\n            // Several framework dev servers fail when Vite negotiates HTTP/2.\n            ALPNProtocols: [\"http/1.1\"],\n            cert: certificates.cert,\n            key: certificates.key,\n          },\n          hmr: {\n            host: settings.host,\n            protocol: \"wss\",\n          },\n        },\n      };\n    },\n    configureServer(server) {\n      if (!settings || !checkCertificateFiles(settings)) return;\n\n      getCertificateFiles();\n      configureLocalHttpsServer(server, settings);\n    },\n  };\n}\n\n/** Host and certificate paths for provisionLocalHttps. */\nexport type ProvisionLocalHttpsOptions = Omit<LocalHttpsOptions, \"enabled\" | \"port\">;\n\n/**\n * Creates trusted certificate files for local HTTPS. Call the function from a setup script, or\n * before you start a framework that reads certificate paths when its config loads, such as Nuxt.\n *\n * When both files exist, the function returns their paths and changes nothing. Otherwise, the\n * function downloads a pinned, checksum-verified mkcert release, adds the mkcert certificate\n * authority to your system trust store, and creates the certificate and private key. mkcert can\n * ask for your password.\n *\n * @param options Host and certificate paths. Each option has a Hydrogen default.\n * @returns The host and the absolute paths to the certificate and the private key.\n * @publicDocs\n */\nexport async function provisionLocalHttps(options: ProvisionLocalHttpsOptions = {}) {\n  const settings = resolveLocalHttpsSettings({ enabled: true, ...options });\n\n  if (!certificateFilesExist(settings)) {\n    await provisionCertificates(settings);\n  }\n\n  return {\n    host: settings.host,\n    certPath: settings.certPath,\n    keyPath: settings.keyPath,\n  };\n}\n\ntype LocalHttpsSettings = {\n  host: string;\n  port: number;\n  certPath: string;\n  keyPath: string;\n};\n\ntype LocalHttpsCertificateFiles = {\n  cert: Buffer;\n  key: Buffer;\n};\n\nfunction resolveLocalHttpsSettings(options: LocalHttpsOptions): LocalHttpsSettings {\n  const host = options.host ?? LOCAL_HTTPS_DEFAULTS.host;\n  const certificateDirectory = join(homedir(), \".shopify\", \"hydrogen\", \"certs\");\n\n  return {\n    host,\n    port: options.port ?? LOCAL_HTTPS_DEFAULTS.port,\n    certPath: resolveCertificatePath(options.certPath ?? join(certificateDirectory, `${host}.pem`)),\n    keyPath: resolveCertificatePath(\n      options.keyPath ?? join(certificateDirectory, `${host}-key.pem`),\n    ),\n  };\n}\n\nfunction resolveCertificatePath(path: string | URL) {\n  if (path instanceof URL) return fileURLToPath(path);\n  if (path === \"~\") return homedir();\n  if (path.startsWith(\"~/\")) return resolve(homedir(), path.slice(2));\n  return isAbsolute(path) ? path : resolve(path);\n}\n\nfunction certificateFilesExist(settings: LocalHttpsSettings) {\n  return existsSync(settings.certPath) && existsSync(settings.keyPath);\n}\n\nasync function ensureCertificateFiles(settings: LocalHttpsSettings): Promise<boolean> {\n  if (certificateFilesExist(settings)) return true;\n\n  // Installing the mkcert certificate authority needs an interactive trust\n  // prompt on first run, which hangs or fails on CI runners.\n  if (isContinuousIntegration()) {\n    return checkCertificateFiles(\n      settings,\n      \"Automatic certificate provisioning is skipped in CI environments (the CI environment variable is set).\",\n    );\n  }\n\n  if (!(await confirmCertificateInstallation(settings.host))) {\n    return checkCertificateFiles(\n      settings,\n      \"Automatic certificate provisioning requires confirmation in an interactive terminal.\",\n    );\n  }\n\n  try {\n    await provisionCertificates(settings);\n    return true;\n  } catch (error) {\n    return checkCertificateFiles(\n      settings,\n      `Automatic certificate provisioning failed:\\n  ${error instanceof Error ? error.message : String(error)}`,\n    );\n  }\n}\n\nfunction checkCertificateFiles(settings: LocalHttpsSettings, provisioningNote?: string) {\n  const missingPaths = [settings.certPath, settings.keyPath].filter((path) => !existsSync(path));\n  if (missingPaths.length === 0) return true;\n\n  const warning = formatMissingCertificateWarning(settings, missingPaths, provisioningNote);\n  if (!emittedMissingCertificateWarnings.has(warning)) {\n    emittedMissingCertificateWarnings.add(warning);\n    process.emitWarning(warning, { type: \"HydrogenLocalHttpsWarning\" });\n  }\n  return false;\n}\n\nfunction formatMissingCertificateWarning(\n  { certPath, host, keyPath }: LocalHttpsSettings,\n  missingPaths: string[],\n  provisioningNote?: string,\n) {\n  const certificateDirectories = [...new Set([dirname(certPath), dirname(keyPath)])];\n  const provisioningFailure = provisioningNote === undefined ? [] : [\"\", provisioningNote];\n\n  return [\n    \"Local HTTPS is disabled because certificate files are missing:\",\n    ...missingPaths.map((path) => `  ${path}`),\n    ...provisioningFailure,\n    \"\",\n    \"Expected certificate files:\",\n    `  Certificate: ${certPath}`,\n    `  Private key: ${keyPath}`,\n    \"\",\n    \"Run the automatic setup:\",\n    \"  npx hydrogen certs install\",\n    \"\",\n    \"Or install and configure mkcert, then generate the certificate:\",\n    \"  macOS: brew install mkcert\",\n    \"  mkcert -install\",\n    `  mkdir -p ${certificateDirectories.map(shellQuote).join(\" \")}`,\n    `  mkcert -cert-file ${shellQuote(certPath)} -key-file ${shellQuote(keyPath)} ${shellQuote(host)}`,\n  ].join(\"\\n\");\n}\n\nfunction readCertificateFiles(settings: LocalHttpsSettings): LocalHttpsCertificateFiles {\n  return {\n    cert: readCertificateFile(settings, \"certificate\", settings.certPath),\n    key: readCertificateFile(settings, \"private key\", settings.keyPath),\n  };\n}\n\nfunction readCertificateFile(settings: LocalHttpsSettings, label: string, path: string) {\n  try {\n    return readFileSync(path);\n  } catch (error) {\n    throw new Error(formatCertificateReadError(settings, label, path, error), { cause: error });\n  }\n}\n\nfunction formatCertificateReadError(\n  { certPath, host, keyPath }: LocalHttpsSettings,\n  label: string,\n  path: string,\n  error: unknown,\n) {\n  const certificateDirectories = [...new Set([dirname(certPath), dirname(keyPath)])];\n  const reason = error instanceof Error ? error.message : String(error);\n\n  return [\n    `Local HTTPS requires a readable ${label} file:`,\n    `  ${path}`,\n    `Reason: ${reason}`,\n    \"\",\n    \"Expected certificate files:\",\n    `  Certificate: ${certPath}`,\n    `  Private key: ${keyPath}`,\n    \"\",\n    \"Install and configure mkcert, then generate the certificate:\",\n    \"  macOS: brew install mkcert\",\n    \"  mkcert -install\",\n    `  mkdir -p ${certificateDirectories.map(shellQuote).join(\" \")}`,\n    `  mkcert -cert-file ${shellQuote(certPath)} -key-file ${shellQuote(keyPath)} ${shellQuote(host)}`,\n  ].join(\"\\n\");\n}\n\nfunction shellQuote(value: string) {\n  return `'${value.replaceAll(\"'\", `'\\\\''`)}'`;\n}\n\nfunction configureLocalHttpsServer(server: ViteDevServer, settings: LocalHttpsSettings) {\n  // The configured port is only a fallback: frameworks that own the listener\n  // (or auto-incremented ports) can bind somewhere else, and the Customer\n  // Account URLs registered in admin must match the port actually served.\n  const resolveBoundPort = () => {\n    const address = server.httpServer?.address();\n    return address && typeof address === \"object\" ? address.port : settings.port;\n  };\n\n  server.middlewares.use((request, response, next) => {\n    request.headers[\"x-forwarded-host\"] ??=\n      request.headers.host ?? `${settings.host}:${resolveBoundPort()}`;\n    request.headers[\"x-forwarded-proto\"] ??= \"https\";\n    stripHttp1OnlyResponseHeaders(response);\n    next();\n  });\n\n  const configureCustomerAccounts = () => {\n    const port = resolveBoundPort();\n    const settingsKey = `${server.config.root}:${settings.host}:${port}`;\n    if (startedCustomerAccountSetups.has(settingsKey)) return;\n    startedCustomerAccountSetups.add(settingsKey);\n\n    void configureCustomerAccountUrls({\n      logger: server.config.logger,\n      root: server.config.root,\n      urls: resolveCustomerAccountUrls(settings.host, port),\n    });\n  };\n\n  if (server.httpServer) {\n    server.httpServer.once(\"listening\", configureCustomerAccounts);\n  } else {\n    configureCustomerAccounts();\n  }\n}\n\nfunction stripHttp1OnlyResponseHeaders(response: ServerResponse) {\n  const originalWriteHead = response.writeHead.bind(response);\n\n  response.writeHead = (\n    statusCode: number,\n    statusMessageOrHeaders?: string | OutgoingHttpHeaders | OutgoingHttpHeader[],\n    headers?: OutgoingHttpHeaders | OutgoingHttpHeader[],\n  ) => {\n    removeStoredHttp1OnlyHeaders(response);\n\n    if (typeof statusMessageOrHeaders === \"string\") {\n      return originalWriteHead(\n        statusCode,\n        statusMessageOrHeaders,\n        sanitizeWriteHeadHeaders(headers),\n      );\n    }\n\n    return originalWriteHead(statusCode, sanitizeWriteHeadHeaders(statusMessageOrHeaders));\n  };\n}\n\nfunction removeStoredHttp1OnlyHeaders(response: ServerResponse) {\n  for (const header of HTTP1_ONLY_RESPONSE_HEADERS) {\n    response.removeHeader(header);\n  }\n}\n\nfunction sanitizeWriteHeadHeaders(headers: OutgoingHttpHeaders | OutgoingHttpHeader[] | undefined) {\n  if (Array.isArray(headers)) return sanitizeHeaderArray(headers);\n  if (headers) return sanitizeHeaderObject(headers);\n  return headers;\n}\n\nfunction sanitizeHeaderObject(headers: OutgoingHttpHeaders) {\n  const sanitizedHeaders: OutgoingHttpHeaders = {};\n\n  for (const [name, value] of Object.entries(headers)) {\n    if (!isHttp1OnlyHeader(name)) sanitizedHeaders[name] = value;\n  }\n\n  return sanitizedHeaders;\n}\n\nfunction sanitizeHeaderArray(headers: OutgoingHttpHeader[]) {\n  const sanitizedHeaders: OutgoingHttpHeader[] = [];\n\n  for (let index = 0; index < headers.length; index += HEADER_PAIR_SIZE) {\n    const name = headers[index];\n    const value = headers[index + 1];\n    if (typeof name === \"string\" && isHttp1OnlyHeader(name)) continue;\n\n    sanitizedHeaders.push(name);\n    if (value !== undefined) sanitizedHeaders.push(value);\n  }\n\n  return sanitizedHeaders;\n}\n\nfunction isHttp1OnlyHeader(name: string) {\n  return HTTP1_ONLY_RESPONSE_HEADERS.has(name.toLowerCase());\n}\n"],"mappings":"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"}

package/dist/vue/cart.d.mts

@@ -18,18 +18,20 @@ type TypedCartProvider<TData extends CartData> = {
     };
   };
 };
+/** Cart provider and composables whose cart state carries the custom fields from your cart server handlers. */
 type TypedCartComponents<TData extends CartData> = {
-  CartProvider: TypedCartProvider<TData>;
-  useCart: TypedUseCart<TData>;
-  useOptionalCart: TypedUseOptionalCart<TData>;
-  useCartActions: typeof useCartActions;
+  /** The provider that creates the cart store. The provider connects the store on mount and destroys the store on unmount. */CartProvider: TypedCartProvider<TData>; /** Returns cart state as a read-only shallow ref. The selector is optional. Without a selector, the ref holds the full cart state. */
+  useCart: TypedUseCart<TData>; /** Returns the slice of cart state that the selector picks as a read-only shallow ref. Outside the provider, the ref holds `undefined`. */
+  useOptionalCart: TypedUseOptionalCart<TData>; /** Returns the `refresh` action. Call `refresh` after a server-side cart mutation that bypasses cart forms. */
+  useCartActions: typeof useCartActions; /** Returns form props, a register function, and pending state for cart forms. */
   useCartForm: typeof useCartForm;
 };
 /**
- * Returns cart actions for reconciling state after out-of-band mutations.
+ * Returns the cart action that syncs the cart after a mutation outside cart forms.
  *
- * Currently exposes {@link CartStore.refresh} — call it after server-side cart
- * mutations that bypass the form system.
+ * Call `refresh` after a server-side cart mutation that bypasses cart forms, such as a server action that creates the cart.
+ *
+ * @returns The `refresh` action.
  *
  * @example
  * ```vue
@@ -42,13 +44,13 @@ type TypedCartComponents<TData extends CartData> = {
  * }
  * </script>
  * ```
+ * @publicDocs
  */
 declare function useCartActions(): CartActions;
 /**
- * Subscribes the {@link CartStore} to the analytics event dispatcher.
+ * Publishes cart analytics events when the cart changes.
  *
- * Call once near the root of your app. Starts tracking on mount via `onMounted`
- * and cleans up via `onScopeDispose`.
+ * Call the composable once near the root of your app. The composable starts tracking on mount and stops when the component's scope ends. The composable throws when you call it outside the cart provider.
  *
  * @example
  * ```vue
@@ -56,19 +58,19 @@ declare function useCartActions(): CartActions;
  * useCartAnalytics();
  * </script>
  * ```
+ * @publicDocs
  */
 declare function useCartAnalytics(): void;
 /**
- * Returns form props, a field register function, and reactive pending state
- * for building cart forms in Vue.
+ * Returns form props, a register function, and pending state for cart forms.
+ *
+ * The form props post to the cart endpoint and send each submission through the cart store. A `beforeSubmit` callback that prevents the event's default skips the cart submission.
  *
- * Unlike the React hook, the Vue variant includes `isPending` — a reactive
- * object with `initial` (`ComputedRef<boolean>`) for the initial cart load
- * and `lines(lineId?)` for checking per-line or any-line pending state.
+ * The pending state holds a computed ref that's `true` during a full cart load, and a function that checks whether one line or any line has a mutation in flight.
  *
- * Note: `interactive: true` returns numeric input attributes but does **not**
- * auto-submit on change — that behavior requires `attachQuantityInput`, which
- * is only wired by the React adapter.
+ * Registering the quantity field with `interactive: true` returns numeric input attributes without auto-submit. Call attachQuantityInput on the input to submit the form when the quantity changes.
+ *
+ * @returns The form props function, the register function, and the pending state.
  *
  * @example
  * ```vue
@@ -87,6 +89,7 @@ declare function useCartAnalytics(): void;
  *   </form>
  * </template>
  * ```
+ * @publicDocs
  */
 declare function useCartForm(): {
   formProps: (opts?: {
@@ -100,11 +103,12 @@ declare function useCartForm(): {
   };
 };
 /**
- * Factory that returns typed cart components and composables matched to your
- * server handler's cart query shape.
+ * Returns a cart provider and composables typed to the cart query in your cart server handlers.
+ * Pass the type of your cart server handlers as the `THandlers` type argument. Every composable's cart state then includes your custom cart fields.
+ *
+ * On mount, the provider points cart requests at `/api/cart` and connects the store. Every composable except the optional cart composable throws when you call it outside the provider.
  *
- * The generic `THandlers` parameter is inferred from your `createCartServerHandlers`
- * call, so every composable's {@link CartState} carries your custom cart fields.
+ * @returns The typed cart provider, the cart state composables, and the cart actions and form composables.
  *
  * @example
  * ```ts
@@ -118,8 +122,9 @@ declare function useCartForm(): {
  *   useCartForm,
  * } = createCartComponents<typeof cartServerHandlers>();
  * ```
+ * @publicDocs
  */
 declare function createCartComponents<THandlers>(): TypedCartComponents<CartDataFromHandlers<THandlers>>;
 //#endregion
-export { createCartComponents, useCartActions, useCartAnalytics };
+export { createCartComponents, useCartAnalytics };
 //# sourceMappingURL=cart.d.mts.map