Skip to main content

Shopify scripts

The ShopifyScripts component and the matching core functions load Shopify's storefront scripts in your storefront. Use the component or functions to set up Standard Actions, analytics, customer privacy consent, and client-side navigation through your router.

In frameworks without a Hydrogen binding, such as Astro, SvelteKit, or SolidStart, import the core functions from @shopify/hydrogen. Render the script tags on the server with getShopifyScriptTags or renderShopifyScriptTags, then call initializeShopifyScripts in the browser.

Import ShopifyScripts from @shopify/hydrogen/react or @shopify/hydrogen/vue.

Render the component once in the root layout of a React Router, Next.js, Vue, or Nuxt app.

Anchor to PropertiesProperties

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.

Anchor to shop
shop
required

The shop's IDs and permanent domain.

Anchor to account
account
boolean

Loads the customer account component. Render shopify-account where you want the account UI to appear.

Anchor to analytics
analytics

The sales channel and custom data for the analytics bus.

Anchor to consent
consent

Which consent script to load and how the analytics bus waits for consent.

Anchor to debug
debug
{ standardEventsInspector?: boolean; }

Development-only debugging tools.

Anchor to i18n
i18n

The country, language, currency, and path prefix for Shopify's scripts. Defaults to US English.

Anchor to inbox
inbox
boolean

Loads Inbox. Render shopify-chat where you want the chat UI to appear.

Anchor to navigate
navigate
(url: string) => void | Promise<void>

Navigates after Shopify's scripts resolve a URL to your app's route. Defaults to a full page load.

Anchor to nonce
nonce
string

Adds a nonce attribute to every script tag.

Anchor to routes
routes

Your app's custom route templates, which Shopify's scripts use to match storefront URLs.

Anchor to shopifyAnalytics
shopifyAnalytics
boolean

Loads Shopify's storefront analytics script. Defaults to true.

Anchor to webMcp
webMcp
boolean

Loads Shopify's WebMCP tools when the browser supports WebMCP. Defaults to true.

Examples

React

import {
createShopifyRouteTemplates,
type ShopifyScriptsI18n,
type ShopifyScriptsShop,
} from "@shopify/hydrogen";
import { ShopifyScripts } from "@shopify/hydrogen/react";
import type { ReactNode } from "react";
import { useNavigate } from "react-router";

const routeTemplates = createShopifyRouteTemplates({});

type LayoutProps = {
shop: ShopifyScriptsShop;
i18n: ShopifyScriptsI18n;
children: ReactNode;
};

export function Layout({ shop, i18n, children }: LayoutProps) {
const navigate = useNavigate();

return (
<html lang="en">
<head>
<ShopifyScripts
shop={shop}
i18n={i18n}
consent={{ mode: "default-banner" }}
navigate={(url) => navigate(url)}
routes={routeTemplates}
/>
</head>
<body>{children}</body>
</html>
);
}

Anchor to Browser setupBrowser setup

Anchor to initializeShopifyScripts
initializeShopifyScripts(
input1
)

Starts Shopify's scripts in the browser for frameworks without a Hydrogen binding. Call it after hydration, with the consent configuration that you passed to getShopifyScriptTags.

The function sets up window.Shopify.routes, and sends a page view event on load and after each navigation that changes the path or query. In the custom banner consent mode, Hydrogen calls your setup callback after the Customer Privacy API loads. A custom banner configuration without a setup callback logs a warning, and analytics events stay blocked. When the browser supports WebMCP, the function also loads Shopify's WebMCP tools. Set webMcp to false to skip them.

Anchor to initializeShopifyScripts-parametersParameters

Anchor to input1
input1
required

The consent configuration, the route settings, and whether to load WebMCP tools.

Anchor to initializeShopifyScripts-returnsReturns

Promise<boolean | void>

A promise that resolves after the WebMCP tools load or fail to load, or right away when the function skips WebMCP.

Anchor to consentpreferencesConsentPreferences

The consent choices that a custom consent setup passes to window.Shopify.customerPrivacy.setTrackingConsent().

Anchor to analytics
analytics
boolean
required

Whether the customer allows analytics tracking.

Anchor to marketing
marketing
boolean
required

Whether the customer allows marketing tracking.

Anchor to preferences
preferences
boolean
required

Whether the customer allows the storefront to remember their preferences.

Anchor to sale_of_data
sale_of_data
boolean
required

Whether the customer allows the sale or sharing of their data.

Examples

TypeScript

import { createShopifyRouteTemplates, initializeShopifyScripts } from "@shopify/hydrogen";

const routeTemplates = createShopifyRouteTemplates({});

export function startShopifyScripts(router: { push: (url: string) => Promise<unknown> }) {
void initializeShopifyScripts({
routes: routeTemplates,
navigate: async (url) => {
await router.push(url);
},
});
}

Anchor to Server-rendered tagsServer-rendered tags

Anchor to getShopifyScriptTags
getShopifyScriptTags(
input1
)

Returns Shopify's storefront script and link tags as descriptors.

Render the descriptors in the document head during server rendering, then call initializeShopifyScripts in the browser. Keep the tags in the returned order. The inline scripts set up globals that later scripts read.

Anchor to getShopifyScriptTags-parametersParameters

Anchor to input1
input1
required

The shop details, the localization, the consent configuration, and the features whose scripts to load.

Anchor to getShopifyScriptTags-returnsReturns

The link tags, the script tags, and a combined list with links first.

Anchor to renderShopifyScriptTags
renderShopifyScriptTags(
options
)

Renders Shopify's storefront script and link tags to HTML strings.

Use the function when your framework accepts raw HTML in the document head.

Anchor to renderShopifyScriptTags-parametersParameters

Anchor to options
options
required

The shop details and the features, such as account and analytics, whose scripts to load.

Anchor to renderShopifyScriptTags-returnsReturns

string[]

One HTML string per tag, with link tags first.

To share one configuration between the server and the browser, build a ShopifyScriptsOptions object and pass the object to getShopifyScriptTags and initializeShopifyScripts. ShopifyScriptsOptions combines ShopifyScriptTagsOptions and InitializeShopifyScriptsOptions.

Examples

TypeScript

import {
getShopifyScriptTags,
type ShopifyScriptsI18n,
type ShopifyScriptsShop,
} from "@shopify/hydrogen";

const shop: ShopifyScriptsShop = {
shopId: process.env.SHOP_ID!,
storefrontId: process.env.PUBLIC_STOREFRONT_ID || "0",
myshopifyDomain: process.env.PUBLIC_STORE_DOMAIN!,
};

const i18n: ShopifyScriptsI18n = { country: "US", language: "EN" };

const { links, scripts } = getShopifyScriptTags({ shop, i18n, consent: { mode: "default-banner" } });

export const head = {
link: links.map(({ attributes }) => attributes),
script: scripts.map(({ attributes, innerHTML }) => ({
...attributes,
...(innerHTML ? { innerHTML } : {}),
})),
};

Anchor to Browser globalsBrowser globals

The scripts create the following globals:

  • window.Shopify.actions: Sends cart changes from the cart store.
  • window.Shopify.analytics: The analytics bus. The bus delivers events from cart analytics and events that you publish to your analytics destinations.
Was this page helpful?