feat(scripts): use c15t to load scripts based on shopper consent preferences by matthewvolk · Pull Request #2659 · bigcommerce/catalyst

matthewvolk · 2025-10-30T21:46:02Z

Note

This PR is a replacement for #2651

What/Why?

This PR adds script loading functionality to Catalyst's consent manager, achieving parity with Stencil's consent-aware script loading behavior.

The implementation replaces the custom <ScriptManagerScripts /> component with the native Script Loader feature of the c15t.com library.

Additionally, the consent categories exposed by c15t are different than the consent categories available in the BigCommerce API. The consent categories in the c15t library are hardcoded, so we added a scriptsTransformer to map BigCommerce's consent categories to C15T's standardized categories:

const BC_TO_C15T_CONSENT_CATEGORY_MAP = {
  ESSENTIAL: 'necessary',
  UNKNOWN: 'necessary', // Matches Stencil behavior of always loading "UNKNOWN" scripts
  FUNCTIONAL: 'functionality',
  ANALYTICS: 'measurement',
  TARGETING: 'marketing',
}

It's also worth noting that we maintain feature parity with Stencil in determining which scripts load based on consent preferences:

If the user has not provided any consent preference (cookie banner still visible): Only ESSENTIAL and UNKNOWN scripts are loaded.
If the user has "Accepted All" consent categories, all scripts load
If the user has "Rejected All" consent categories, only ESSENTIAL and UNKNOWN scripts load.

Testing

Demo video:
https://github.com/user-attachments/assets/7f859c23-8419-46e7-b86e-a1e24127879a

Migration

This PR modifies the following files that you may encounter merge conflicts with:

core/app/[locale]/layout.tsx:
- Added ScriptsFragment import and inclusion in RootLayoutMetadataQuery
- Added scriptsTransformer import
- Transformed scripts are now passed to <ConsentManager scripts={scripts}>
- Resolution tip: The ConsentManager component now requires a scripts prop. You'll need to query scripts using the ScriptsFragment and transform them via scriptsTransformer() before passing them to the component.
core/components/consent-manager/index.tsx and consent-providers.tsx:
- Both now accept and forward a scripts prop
- ConsentManagerProvider passes scripts to ClientSideOptionsProvider
- Resolution tip: Ensure the scripts prop flows through: ConsentManager → ConsentManagerProvider → ClientSideOptionsProvider
New files added:
- core/components/consent-manager/scripts-fragment.ts - GraphQL fragment for querying scripts
- core/data-transformers/scripts-transformer.ts - Transforms BC scripts to C15T format
- Resolution tip: These files should not conflict, but if you've added similar functionality, consider consolidating the logic.

If you've customized your consent manager implementation, ensure that:

Scripts are queried in your layout/page where the ConsentManager is rendered
The scriptsTransformer is applied to the raw script data before passing to ConsentManager
The scripts prop is threaded through all consent manager components

changeset-bot · 2025-10-30T21:46:05Z

🦋 Changeset detected

Latest commit: 675089c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@bigcommerce/catalyst-core	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-10-30T21:46:06Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
catalyst-b2b	Ready	Preview	Comment	Oct 31, 2025 8:22pm
catalyst-canary	Ready	Preview	Comment	Oct 31, 2025 8:22pm

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
catalyst	Ignored			Oct 31, 2025 8:22pm

chanceaclark · 2025-10-30T22:23:56Z

+  // eslint-disable-next-line no-console
+  console.warn(
+    `[scripts-transformer] Unknown BigCommerce Script Consent Category ` +
+      `"${bigCommerceCategory}", defaulting to UNKNOWN`,
+  );


This will probably log in production. We probably want to remove this.

Remove or just run when not in prod?

I'd just remove here, otherwise we'd need to add some sort of invariant logger here.

jorgemoya

💯 , love how clean this is. Minor observations before the final approve 👍 .

jorgemoya · 2025-10-31T15:46:07Z

+  // eslint-disable-next-line no-console
+  console.warn(
+    `[scripts-transformer] Unknown BigCommerce Script Consent Category ` +
+      `"${bigCommerceCategory}", defaulting to UNKNOWN`,
+  );


Remove or just run when not in prod?

jorgemoya · 2025-10-31T15:47:35Z

+          }
+          entityId
+          consentCategory
+          location


Should we remove location since we don't use it?

Yeah good catch, we can always add it back later when the library adds support (which they are considering)

jorgemoya · 2025-10-31T15:47:48Z

+          integrityHashes {
+            hash
+          }


Are we still using integrityHashes for anything?

We should be.

Good catch! I added a fix that

.map()'s over site.content.scripts.edges.node.integrityHashes

Filters out falsy (null)

If resulting array contains hashes, join them with a single space (following HTML spec)

Add them to the arbitrary attributes object to be added to the <script> element when rendered

…erences

…erences (#2659)

matthewvolk requested a review from a team October 30, 2025 21:46

vercel Bot deployed to Preview – catalyst-b2b October 30, 2025 21:47 View deployment

vercel Bot deployed to Preview – catalyst-canary October 30, 2025 21:47 View deployment

matthewvolk force-pushed the feat/consent-manager-script-loader branch from f52d125 to 8542b96 Compare October 30, 2025 21:47

vercel Bot deployed to Preview – catalyst-b2b October 30, 2025 21:48 View deployment

vercel Bot deployed to Preview – catalyst-canary October 30, 2025 21:49 View deployment

chanceaclark reviewed Oct 30, 2025

View reviewed changes

jorgemoya reviewed Oct 31, 2025

View reviewed changes

matthewvolk force-pushed the feat/consent-manager-script-loader branch 2 times, most recently from e5bb5e3 to 3b51c8a Compare October 31, 2025 18:16

vercel Bot deployed to Preview – catalyst-b2b October 31, 2025 18:18 View deployment

vercel Bot deployed to Preview – catalyst-canary October 31, 2025 18:18 View deployment

chanceaclark approved these changes Oct 31, 2025

View reviewed changes

jorgemoya approved these changes Oct 31, 2025

View reviewed changes

feat(scripts): use c15t to load scripts based on shopper consent pref…

675089c

…erences

matthewvolk force-pushed the feat/consent-manager-script-loader branch from 3b51c8a to 675089c Compare October 31, 2025 20:20

vercel Bot deployed to Preview – catalyst-b2b October 31, 2025 20:22 View deployment

vercel Bot deployed to Preview – catalyst-canary October 31, 2025 20:22 View deployment

matthewvolk added this pull request to the merge queue Oct 31, 2025

Merged via the queue into canary with commit abaa461 Oct 31, 2025
11 checks passed

matthewvolk deleted the feat/consent-manager-script-loader branch October 31, 2025 20:24

This was referenced Oct 31, 2025

Version Packages (canary) #2575

Merged

Version Packages (canary) matthewvolk/catalyst#1

Open

jamesqquick pushed a commit that referenced this pull request Feb 11, 2026

feat(scripts): use c15t to load scripts based on shopper consent pref…

c8918d3

…erences (#2659)

chanceaclark pushed a commit that referenced this pull request Apr 27, 2026

feat(scripts): use c15t to load scripts based on shopper consent pref…

41e9cf2

…erences (#2659)

Conversation

matthewvolk commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why?

Testing

Migration

Uh oh!

changeset-bot Bot commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jorgemoya left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

matthewvolk commented Oct 30, 2025 •

edited

Loading

changeset-bot Bot commented Oct 30, 2025 •

edited

Loading

vercel Bot commented Oct 30, 2025 •

edited

Loading