CHECKOUT-9450: Lazy load payment strategies through essential build #2989

davidchin · 2025-09-01T04:42:37Z

What/Why?

checkout-sdk-js currently bundles all payment, shipping, and checkout button strategies for every payment provider, regardless of whether they are enabled by the merchant. This leads to unnecessary code in the main bundle, increasing its size and reducing performance.

To address this problem, the following changes are introduced:

Added a new export, @bigcommerce/checkout-sdk/essential, which excludes all payment, shipping, and checkout button strategies from the bundle.
Added an ESM build, allowing the library to be fully tree-shakable.
Updated strategy loading so that strategies are imported from @bigcommerce/checkout-sdk/integrations/* on the application side and passed into CheckoutService only when needed. This enables splitting strategies into separate chunks based on the component that loads them.

// App.tsx
import { createCheckoutService } from '@bigcommerce/checkout-sdk/essential';

const service = createCheckoutService();

// PayPalCommercePaymentMethod.tsx
import { createPayPalCommercePaymentStrategy } from '@bigcommerce/checkout-sdk/integrations/paypal-commerce';

await service.initializePayment({
    methodId: 'paypal',
    integrations: [createPayPalCommercePaymentStrategy],
});

To reduce risk during the initial rollout, strategies will still be bundled as usual while the CHECKOUT-9450.lazy_load_payment_strategies experiment is active. We will compare the bundled strategies with those passed in from checkout-js and log any discrepancies in Sentry. Once we confirm that all passed-in strategies consistently match the existing ones, we will remove the bundled strategies.

Rollout/Rollback

Disable CHECKOUT-9450.lazy_load_payment_strategies experiment

Testing / Proof

The screenshots below show the improvements after the experiment is fully rolled out and the old code removed.

Before

716kb gzipped size for the initial scripts

After

546kb gzipped size for the initial scripts - ~24% improvement

This screenshot shows that payment methods still load as expected.

This screenshot shows that the error logger works as expected.

davidchin · 2025-09-15T01:55:20Z

package.json

+  "main": "dist/cjs/checkout-sdk.js",
+  "module": "dist/esm/checkout-sdk.js",
+  "typings": "dist/types/checkout-sdk.d.ts",
+  "exports": {


This change sets up multiple entry points for the package. See https://docs.npmjs.com/cli/v11/configuring-npm/package-json#exports

davidchin · 2025-09-15T02:02:24Z

packages/core/project.json

                "commands": [
                    "tsc --outDir ../../temp --declaration --emitDeclarationOnly",
                    "api-extractor run --config api-extractor/checkout-sdk.json & api-extractor run --config api-extractor/checkout-button.json & api-extractor run --config api-extractor/embedded-checkout.json & api-extractor run --config api-extractor/internal-mappers.json",
+                    "find src/generated/integrations -name 'api-extractor.json' | xargs -I {} -P 8 sh -c 'cd \"$(dirname \"{}\")\" && npx api-extractor run --config api-extractor.json'",


Since each payment integration has is own entry point, e.g.: @bigcommerce/checkout-sdk/integrations/paypal-commerce, we need to roll up the TS definitions for each one.

davidchin · 2025-09-15T02:16:35Z

packages/core/src/checkout/create-checkout-service.ts

-        defaultPaymentStrategyFactories,
+        paymentStrategyFactories,
+        // TODO: Replace once CHECKOUT-9450.lazy_load_payment_strategies experiment is rolled out
+        // process.env.ESSENTIAL_BUILD ? {} : paymentStrategyFactories,


Payment integration strategies will be excluded from the essential build once the experiment is fully rolled out. During the build phase, TerserJS will remove paymentStrategyFactories from the bundle output, as it is treated as dead code.

davidchin · 2025-09-15T02:24:53Z

packages/workspace-tools/src/generators/auto-export/auto-export.ts

+    };
+}
+
+async function createPackageExports({


This function generates content like the following:

packages/core/src/generated/integrations/credit-card/index.ts

export { createCreditCardPaymentStrategy } from '../../../../../credit-card-integration/src';

packages/core/src/generated/integrations/paypal-commerce

export { createPayPalCommerceCustomerStrategy, createPayPalCommerceCreditCustomerStrategy, createPayPalCommerceVenmoCustomerStrategy, createPayPalCommerceFastlaneCustomerStrategy } from '../../../../../paypal-commerce-integration/src'; export { createPayPalCommercePaymentStrategy, createPayPalCommerceCreditPaymentStrategy, createPayPalCommerceVenmoPaymentStrategy, createPayPalCommerceAlternativeMethodsPaymentStrategy, createPayPalCommerceCreditCardsPaymentStrategy, createPayPalCommerceRatePayPaymentStrategy, createPayPalCommerceFastlanePaymentStrategy } from '../../../../../paypal-commerce-integration/src'; export { createPayPalCommerceButtonStrategy, createPayPalCommerceCreditButtonStrategy, createPayPalCommerceVenmoButtonStrategy, createPayPalCommerceAlternativeMethodsButtonStrategy } from '../../../../../paypal-commerce-integration/src';

It also generates content for its corresponding api-extractor.json.

davidchin · 2025-09-15T02:33:01Z

packages/core/src/payment-integration/register-integrations.ts

+        const { Sentry } = window as SentryWindow;
+
+        if (Sentry?.captureMessage) {
+            Sentry.captureMessage(message);


As mentioned in the comment, the plan is to start with a soft rollout. We’ll first compare the data passed in from checkout-js against the existing registered strategies. If everything aligns, we’ll proceed to remove the existing registration.

…ial build

davidchin force-pushed the lazy_strategies branch 5 times, most recently from 8371880 to 4ed2273 Compare September 5, 2025 06:09

davidchin marked this pull request as ready for review September 5, 2025 06:20

davidchin requested review from a team as code owners September 5, 2025 06:20

davidchin mentioned this pull request Sep 5, 2025

CHECKOUT-9388: Lazy load payment strategies by importing them on demand bigcommerce/checkout-js#2563

Merged

davidchin force-pushed the lazy_strategies branch 7 times, most recently from 32cf86e to fa6553f Compare September 12, 2025 03:04

davidchin force-pushed the lazy_strategies branch 2 times, most recently from 4fe1d7e to baee36d Compare September 15, 2025 01:41

davidchin commented Sep 15, 2025

View reviewed changes

davidchin force-pushed the lazy_strategies branch from baee36d to 9fa9054 Compare September 15, 2025 06:17

davidchin force-pushed the lazy_strategies branch from deb8126 to 3ee2141 Compare September 23, 2025 00:09

This was referenced Sep 23, 2025

CHECKOUT-9450: Export ESM modules and separate payment integration strategies from core bundle #3011

Merged

CHECKOUT-9388: Lazy load customer strategies by importing them on demand bigcommerce/checkout-js#2592

Merged

davidchin force-pushed the lazy_strategies branch from 3ee2141 to 270403c Compare September 29, 2025 00:39

feat(core): CHECKOUT-9450 Lazy load payment strategies through essent…

3f76e30

…ial build

davidchin force-pushed the lazy_strategies branch from 270403c to 3f76e30 Compare September 29, 2025 01:45

animesh1987 approved these changes Sep 29, 2025

View reviewed changes

serhii-tkachenko approved these changes Sep 30, 2025

View reviewed changes

bc-nick approved these changes Sep 30, 2025

View reviewed changes

davidchin merged commit 95394f6 into master Oct 1, 2025
9 checks passed

davidchin deleted the lazy_strategies branch October 1, 2025 01:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

CHECKOUT-9450: Lazy load payment strategies through essential build #2989

CHECKOUT-9450: Lazy load payment strategies through essential build #2989

Uh oh!

davidchin commented Sep 1, 2025 •

edited

Loading

Uh oh!

davidchin Sep 15, 2025

Uh oh!

davidchin Sep 15, 2025

Uh oh!

davidchin Sep 15, 2025

Uh oh!

davidchin Sep 15, 2025

Uh oh!

davidchin Sep 15, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

CHECKOUT-9450: Lazy load payment strategies through essential build #2989

CHECKOUT-9450: Lazy load payment strategies through essential build #2989

Uh oh!

Conversation

davidchin commented Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why?

Rollout/Rollback

Testing / Proof

Before

After

Uh oh!

davidchin Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

davidchin Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

davidchin Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

davidchin Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

davidchin Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

davidchin commented Sep 1, 2025 •

edited

Loading