DocsStorefrontCatalystGuides

Install Scripts in Catalyst

You can add third-party scripts, such as analytics, marketing tags, and widgets, to your Catalyst storefront in two ways:

  1. Add scripts in your code using Next.js’s <Script> component.
  2. Use BigCommerce Script Manager in your store’s control panel to inject scripts without code changes.

Every additional script has a performance cost. Third-party scripts can increase page load time, block rendering, or add runtime overhead on the client. This applies whether scripts are added manually in code or through Script Manager. Be intentional about which scripts you include, where they load (head or body), and when they execute. Review and remove unused scripts periodically, and test storefront performance after adding or updating scripts.

Add scripts in code with the Next.js <Script> component

Because Catalyst is built on Next.js, you can directly include scripts in your application code using the Next.js <Script> component. This approach gives you fine-grained control over when scripts load (for example, immediately, after page load, or during idle time) through the script’s loading strategy. The following example adds an external script in a page component:

import Script from 'next/script';
export default function MyPage() {
  return (
    <>
      {/* Other page content */}
      <Script src="https://example.com/script.js" strategy="afterInteractive" />
    </>
  );
}

Next.js injects and loads the script at the time the strategy specifies. See the Next.js documentation on the <Script> component for details on all available props and strategies.

When adding scripts manually via the Next.js <Script> component, Catalyst does not automatically manage user consent. Scripts that set cookies or perform tracking (for example analytics, advertising, or personalization) may execute immediately, which can violate GDPR or similar privacy regulations if user consent has not been obtained. If a script requires cookie consent, prefer adding it through BigCommerce Script Manager, which integrates with Catalyst’s consent management (via c15t) and ensures non-essential scripts are deferred until the shopper grants consent.

Add scripts with Script Manager

BigCommerce Script Manager lets you manage third-party scripts in the control panel instead of in code, and lists all the scripts installed on your store. Use it to add tracking pixels, analytics tags, chat widgets, and other scripts by pasting them into the control panel.

In the control panel, go to Storefront > Script Manager. Create a new script, give it a name, and set options such as:

  • Location – where the script is injected, for example, the <head> or the bottom of the <body> of your storefront pages.
  • Pages where it applies – for example, All Pages or Storefront Pages. Catalyst fetches scripts that apply to All Pages or Storefront Pages and ignores other options, such as Order Confirmation.
  • Script content or URL – you can either paste inline script code or provide an external script URL.
  • Consent category – categorize the script (Essential, Functional, Analytics, or Targeting) for privacy consent purposes.

After you save a script in Script Manager, Catalyst picks it up and includes it on your storefront at runtime, with no changes to your Catalyst code.

How Catalyst loads Script Manager scripts

When your storefront loads, Catalyst uses the GraphQL Storefront API to retrieve the scripts defined in Script Manager. Its built-in GraphQL fragment includes all scripts configured for All Pages or Storefront Pages, with each script’s content or URL, location, consent category, and so on:

  1. Fetch scripts via GraphQL: The Catalyst app’s root layout query requests the list of scripts from the store (using a ScriptsFragment fragment). This returns up to 50 scripts and their properties.
  2. Transform script data: The raw script data from BigCommerce is passed through a scriptsTransformer function in Catalyst. This transformer maps BigCommerce’s script fields into the format expected by the c15t script loader. For example, it converts the script’s location to a target placement (head or body), uses the script’s entityId as a stable script ID, and maps the BigCommerce consent category (Essential, Functional, Analytics, or Targeting) to c15t’s category names (necessary, functionality, measurement, marketing).
  3. Inject via c15t: Catalyst uses c15t, an open-source consent management library, to load the scripts on the client side. The transformed scripts list is passed to c15t’s <ClientSideOptionsProvider>, which creates the corresponding <script> elements in the browser. c15t ensures each script is injected into the appropriate part of the page (head or body) and manages their lifecycle.
  4. Consent management: If your store has cookie consent enabled, c15t’s consent manager defers non-essential scripts until the shopper grants consent for their category. For example, a script categorized as Analytics (c15t’s measurement category) doesn’t run until the shopper consents to analytics cookies. After consent, c15t loads any pending scripts for the allowed categories. If cookie consent is disabled in your store’s settings, all scripts load immediately.

Script Manager decouples script management from your codebase. Non-developers can add or remove third-party integrations without code changes, and the scripts load in line with the shopper’s consent choices.

Next steps