Feat: V6 Context Provider #688

EvanReinstein · 2025-09-26T14:16:35Z

This PR adds a Provider wrapper that can be used to access SDK instance context. This is an initial set of basic changes that leverage paypal-js's loadCoreSdkScript and adds SSR related conditions to prevent/guard against running client-side code.

There is a corresponding PR here that implements the Provider and renders a PayPal and Venmo button. In order to test the Provider make sure to have cloned both repos and leverage npm link to create a symlink between the changes on this branch in react-paypal-js and the pre-built React one time payment example.

See the PR linked above for more specific step-by-step instructions.

* initial package.json and rollup updates, changes tsconfig to bundler and adds v6 specific tsconfig * upgrade react-paypal-js typescript package to v5.3.3 * update tsconfig for v6 namespace * chore: add changeset * align rollup version and update playwright yml * change playwright.yml download deps command * update actions checkout and setup-node to v4 * update .nvmrc * try different method for installing dependencies * fix package dependency issues related to rollup and terser * revert change to download deps step * update package-lock * test fix for rollup option deps bug * update build script * test adding cache to setup node action, update install command, and remove rollup force install in github workflows * re-add force rollup install in github workflows * run npm install to update package-lock with new package versions from typescript upgrade * revert changes to download deps and setup node steps in github workflows * install with update to package.json * leverage fresh package-lock and remove all artifactory package resolution paths * fix check annotations warnings * add new line at the end of gitignore

…provider

changeset-bot · 2025-09-26T14:16:39Z

🦋 Changeset detected

Latest commit: 1f7404c

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

This PR includes changesets to release 2 packages

Name	Type
@paypal/react-paypal-js	Minor
@paypal/paypal-js	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

packages/react-paypal-js/src/v6/components/PayPalInstanceProvider.tsx

EvanReinstein · 2025-09-26T14:22:55Z

packages/react-paypal-js/src/v6/components/PayPalInstanceProvider.tsx

+    scriptOptions: LoadCoreSdkScriptOptions;
+}
+
+export const PayPalInstanceProvider: React.FC<PayPalInstanceProviderProps> = ({


In a fit of spontaneity I used "instance" as a key term in the names for the provider and related files, context state, etc.

I am not attached to this and am willing to make any changes. Originally I was calling this v6PayPalScriptProvider but felt that the provider was really providing the SDK instance. Any thoughts here would be appreciated.

I think this name makes sense, but what about adding sdk to make it clear what PayPal thing is being provided, i.e. PayPalSdkInstanceProvider?

I like that @kand I'll update and see what other folks have to say.

EvanReinstein · 2025-09-26T14:52:02Z

packages/react-paypal-js/src/v6/utils.ts

Added a v6-specific utils file. Only the folders/files within the src/v6/ path get built for V6 and importing utils from the V5 utils file was causing some issues. There is probably a workaround but this was the most straightforward solution.

kand

Looks good!

kand · 2025-09-26T15:00:57Z

packages/react-paypal-js/src/v6/components/PayPalInstanceProvider.tsx

+    scriptOptions: LoadCoreSdkScriptOptions;
+}
+
+export const PayPalInstanceProvider: React.FC<PayPalInstanceProviderProps> = ({


I think this name makes sense, but what about adding sdk to make it clear what PayPal thing is being provided, i.e. PayPalSdkInstanceProvider?

kand · 2025-09-26T15:01:38Z

packages/paypal-js/src/v6/index.ts

    validateArguments(options);
+
+    // SSR safeguard
+    if (typeof document === "undefined") {


Makes sense to me, but is this the standard way to check for SSR? I don't have much SSR experience so I'm curious.

Also, what's the difference between this check and isServer checking if typeof window === "undefined"? Would it make sense to use the same strategy in both places?

Shoot I meant to replace this with isServer.

I want to standardize on one isServer check, which currently is typeof window === "undefined". From looking at a few different packages (stripe, square, adyen-web) there are a few ways to do this, and typeof window === "undefined" is just one of those.

… paypal-js

…t options

EvanReinstein · 2025-10-01T16:09:12Z

packages/react-paypal-js/src/v6/components/PayPalSdkInstanceProvider.tsx

+                value: INSTANCE_LOADING_STATE.PENDING,
+            });
+        }
+    }, []); // Run once on mount


Purposefully using an empty array here in order to run this effect only on mount.

It looks like github / react is unhappy that state.loadingStatus is missing from the dependency array. I think we'll need it here because state is technically state that should cause this useEffect to update. What about putting a check at the top of the effect with a ref that checks if it's been run already?

Yes, going to have to add a useRef to track this. At first I thought that since loadingStatus !== Initial after the first mount that a useRef wasn't necessary since the condition will never be fulfilled.

Massive but here...but it is safer and more explicit to leverage useRef. Let me push a change

EvanReinstein · 2025-10-01T16:10:35Z

packages/react-paypal-js/src/v6/components/PayPalProvider.tsx

+        state.scriptOptions,
+    ]);
+
+    // Separate effect for eligibility - runs after instance is created


Currently going with calling eligibility for all use cases. Originally we'd discussed passing the eligibility response to the provider and then conditionally calling eligibility. I'd like to update this portion of the provider when we implement the eligibility hook.

gregjopa · 2025-10-01T16:21:55Z

packages/paypal-js/src/utils.ts

    return newScript;
 }
+
+export const isServer = typeof window === "undefined";


Two minor things:

should we make this a function so its callable in different contexts?

Can we also check document? When doing server-side rendering, I think some environments may set window so its safer to check document. Might as well check for both being defined.

Suggested change

export const isServer = typeof window === "undefined";

export function isServer() {

return typeof window === "undefined" && typeof document === "undefined";

}

…s present

…re/DTPPCPSDK-3479-provider

…l/paypal-js into feature/DTPPCPSDK-3479-provider

kand

A couple small things, but looks great otherwise!

kand · 2025-10-01T19:35:32Z

packages/react-paypal-js/src/v6/components/PayPalSdkInstanceProvider.tsx

+                value: INSTANCE_LOADING_STATE.PENDING,
+            });
+        }
+    }, []); // Run once on mount


It looks like github / react is unhappy that state.loadingStatus is missing from the dependency array. I think we'll need it here because state is technically state that should cause this useEffect to update. What about putting a check at the top of the effect with a ref that checks if it's been run already?

kand · 2025-10-01T19:39:07Z

packages/react-paypal-js/src/v6/components/PayPalSdkInstanceProvider.tsx

+        if (isServer()) {
+            return;
+        }


Given the note on line 101:

SDK loading effect - only runs on client (useEffect doesn't run during SSR)

Do you need this isServer check here?

Good catch!

hamzanasir

Great job @EvanReinstein! Left a few comments

hamzanasir · 2025-10-01T20:07:52Z

packages/react-paypal-js/src/v6/components/PayPalSdkInstanceProvider.tsx

+ *   {children}
+ * </PayPalSdkInstanceProvider>
+ */
+export const PayPalSdkInstanceProvider: React.FC<


I would actually vote name this more generic. Something like <PayPalProvider /> or <PayPalCheckoutProvider />. I think that the word SdkInstance doesn't hold a lot of meaning for the merchant since the only consumers of this provider will be our hooks/components. Stripe has something similar I believe:

<CheckoutProvider stripe={stripePromise} options={{clientSecret: promise}}> <CheckoutForm /> </CheckoutProvider>

Point taken!

hamzanasir · 2025-10-01T20:08:26Z

packages/react-paypal-js/src/v6/components/PayPalSdkInstanceProvider.tsx

+                value: INSTANCE_LOADING_STATE.PENDING,
+            });
+        }
+    }, []); // Run once on mount


hamzanasir · 2025-10-01T20:13:31Z

packages/react-paypal-js/src/v6/components/PayPalSdkInstanceProvider.tsx

+ *
+ * @example
+ * <PayPalSdkInstanceProvider
+ *   createInstanceOptions={{


Once again I don't think createInstanceOptions will ring a bell to anyone who hasn't used the v6 SDK before. I would vote for a more abstracted flattened provider like this one:

<PayPalCheckoutProvider components: ["paypal-payments"], clientToken: token, environment: "sandbox" > {children} </PayPalSdkInstanceProvider>

Ok I considered this and tbh it would be helpful in terms of inline objects passed as props causing rerenders, which the provider then needs to manage.

If other folks don't have strong opinions against this I'll go down this path.

@hamzanasir Alrighty, I updated the naming convention across the board. Lmk what you think

packages/react-paypal-js/src/v6/components/PayPalSdkInstanceProvider.tsx

hamzanasir

Great work @EvanReinstein!

packages/paypal-js/src/utils.ts

hamzanasir · 2025-10-03T16:38:03Z

packages/paypal-js/src/v6/index.ts

            url: url.toString(),
            onSuccess: () => {
-                if (!window.paypal) {
+                if (isServerEnv || !window.paypal) {


Would we even get to this line of code if isServerEnv is true? I would assume the above SSR safeguard does an early return

Oh shoot, correct. Let me push that change

hamzanasir · 2025-10-03T16:39:02Z

packages/react-paypal-js/src/v6/components/PayPalProvider.tsx

+ * You can pass options directly without manual memoization.
+ *
+ * @example
+ * <PayPalSdkInstanceProvider


Suggested change

* <PayPalSdkInstanceProvider

* <PayPalProvider

Great catch!

hamzanasir · 2025-10-03T16:47:44Z

packages/react-paypal-js/src/v6/components/PayPalProvider.tsx

+        memoizedCreateOptions,
+        memoizedScriptOptions,
+        state.createInstanceOptions,
+        state.scriptOptions,


I'm a little confused by this logic. Why are we listening to both options for changes?

hamzanasir · 2025-10-03T16:49:22Z

packages/react-paypal-js/src/v6/components/PayPalProvider.tsx

+            return;
+        }
+
+        let isSubscribed = true;


Can you explain what this does exactly? To my knowledge once the hook calls the cleanup function this useEffect will be lost so it shouldn't run anymore. Do we need this isSubscribed logic?

It's an attempt to prevent loadSdk from continuing to run with an update happening in the background. It's async, and its steps are also async. It probably would benefit from a check before await loadCoreSdkScript though, since we're already in deferred operation at that point.

I think if you wanted to clean it up, you could use an AbortController instead. Haven't looked at what APIs are used in loadCoreSdkScript to see if any of them actually take an AbortSignal, but you could write your own, if this is going to be a common pattern.

imbrian · 2025-10-06T15:26:50Z

packages/paypal-js/src/v6/index.ts

+
+    // SSR safeguard
+    if (isServerEnv) {
+        return Promise.resolve(null);


Do we want a noop here or a warning? Presumably this would only be called in a useEffect, which won't be run until the client. Seems like this being called on the server is probably more indicative of an integration problem.

Great point on adding a warning!

imbrian · 2025-10-06T15:48:10Z

packages/react-paypal-js/src/v6/components/PayPalProvider.tsx

+            return;
+        }
+
+        let isSubscribed = true;


It's an attempt to prevent loadSdk from continuing to run with an update happening in the background. It's async, and its steps are also async. It probably would benefit from a check before await loadCoreSdkScript though, since we're already in deferred operation at that point.

I think if you wanted to clean it up, you could use an AbortController instead. Haven't looked at what APIs are used in loadCoreSdkScript to see if any of them actually take an AbortSignal, but you could write your own, if this is going to be a common pattern.

imbrian · 2025-10-06T16:24:56Z

packages/react-paypal-js/src/v6/components/PayPalProvider.tsx

+        const loadEligibility = async () => {
+            try {
+                const eligiblePaymentMethods =
+                    await state.sdkInstance?.findEligibleMethods({});


Does there need to be a mechanism for the merchant to override the necessity of this call? Can the merchant provide their own server-side eligibility determination?

Yes, that work is forthcoming 👍 and this is more of a placeholder.

…l/paypal-js into feature/DTPPCPSDK-3479-provider

EvanReinstein added 7 commits September 23, 2025 13:19

add ssr checks to load core sdk script func and add initial instance …

fe5feee

…provider

add a basic set of hooks

8f8c959

update exports

5110af3

mark usePayPalInstance hook as exportable

ba846db

add isServer util and apply where appropriate

ede8236

clean up usePayPalInstance file

414227f

EvanReinstein requested a review from a team as a code owner September 26, 2025 14:16

EvanReinstein commented Sep 26, 2025

View reviewed changes

packages/react-paypal-js/src/v6/components/PayPalInstanceProvider.tsx Outdated Show resolved Hide resolved

EvanReinstein commented Sep 26, 2025

View reviewed changes

EvanReinstein added 2 commits September 26, 2025 09:23

update exports

eba55a7

create v6 specific utils file

3fa346e

EvanReinstein commented Sep 26, 2025

View reviewed changes

kand approved these changes Sep 26, 2025

View reviewed changes

EvanReinstein added 7 commits September 26, 2025 14:28

add reducer to manage various state, fix missed isServer condition in…

599f85f

… paypal-js

update paypal sdk instance provider name

f5333b2

remove json.stringify operation from memoizedOptions

853694b

clean up useMemo

c59a0bb

clean up useMemo import

cfbfb0e

update provider to account for useEffect during ssr

f27e7f8

add tests for client-side and server-side instance provider

b532494

EvanReinstein mentioned this pull request Sep 29, 2025

Test: V6 Instance Provider paypal-examples/v6-web-sdk-sample-integration#79

Closed

EvanReinstein added 7 commits September 30, 2025 10:12

add instance provider context test

934c25a

add context test and clean up other provider tests

0005534

update initial to pending state useEffect with empty dependency array

bea46b3

configure provider to handle memoization of create instance and scrip…

3f7ea83

…t options

memoize context to prevent rerenders

fe1e293

remove duplicate isServer

4755ad3

swap deep equality check packages

ace1a38

EvanReinstein commented Oct 1, 2025

View reviewed changes

gregjopa reviewed Oct 1, 2025

View reviewed changes

EvanReinstein added 3 commits October 1, 2025 11:33

update isServer to a function that also checks whether the document i…

e5dc00e

…s present

fix tests and missed isServer uses

8397495

Merge branch 'main' of https://github.com/paypal/paypal-js into featu…

b5145df

…re/DTPPCPSDK-3479-provider

EvanReinstein force-pushed the feature/react-paypal-js-v6 branch from d41303e to a142270 Compare October 1, 2025 17:40

Merge branch 'feature/react-paypal-js-v6' of https://github.com/paypa…

07dd9d1

…l/paypal-js into feature/DTPPCPSDK-3479-provider

kand reviewed Oct 1, 2025

View reviewed changes

EvanReinstein added 2 commits October 1, 2025 15:11

remove isServer from eligibility useEffect

7ffdce2

add changeset

2093f29

hamzanasir reviewed Oct 1, 2025

View reviewed changes

EvanReinstein added 5 commits October 1, 2025 15:41

add ref for initial hydration

c96a7e2

remove abort controller

604c6dc

flatten create instance options props object

12b2431

update naming convention

f987569

update tests to reflect name and prop passing changes

e19df62

hamzanasir approved these changes Oct 3, 2025

View reviewed changes

EvanReinstein added 3 commits October 3, 2025 13:00

remove dead code isServer check

3563130

update jsdoc

c96c47d

update imports to correct values

7449a90

imbrian reviewed Oct 6, 2025

View reviewed changes

EvanReinstein added 4 commits October 6, 2025 14:03

add console warning to loadCoreSdkScript

77c56b9

remove create instance and script options from reducer state

8e624e3

remove sdkInstance check in loading useEffect

ed2b6ac

Merge branch 'feature/react-paypal-js-v6' of https://github.com/paypa…

1f7404c

…l/paypal-js into feature/DTPPCPSDK-3479-provider

EvanReinstein merged commit dda72d7 into feature/react-paypal-js-v6 Oct 7, 2025
2 checks passed

EvanReinstein deleted the feature/DTPPCPSDK-3479-provider branch October 7, 2025 14:27

-export const isServer = typeof window === "undefined";
+export function isServer() {
+  return typeof window === "undefined" && typeof document === "undefined";
+}

Feat: V6 Context Provider #688

Feat: V6 Context Provider #688

Conversation

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

Uh oh!

Uh oh!

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

Uh oh!

🦋 Changeset detected

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!

kand left a comment

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!

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!

kand left a comment

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!

hamzanasir left a comment

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hamzanasir 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

EvanReinstein commented Sep 26, 2025 •

edited

Loading

changeset-bot bot commented Sep 26, 2025 •

edited

Loading

imbrian Oct 6, 2025 •

edited

Loading

imbrian Oct 6, 2025 •

edited

Loading