Feat: V6 Context Provider

.changeset/dirty-seas-clean.md

@@ -0,0 +1,6 @@
+---
+"@paypal/react-paypal-js": minor
+"@paypal/paypal-js": minor
+---
+
+Add V6 instance provider and context hook

packages/paypal-js/src/utils.ts

@@ -158,3 +158,7 @@ function createScriptElement(
 
     return newScript;
 }
+
+export function isServer(): boolean {
+    return typeof window === "undefined" && typeof document === "undefined";
+}

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

@@ -1,4 +1,4 @@
-import { insertScriptElement } from "../utils";
+import { insertScriptElement, isServer } from "../utils";
 import type {
     PayPalV6Namespace,
     LoadCoreSdkScriptOptions,
@@ -8,6 +8,16 @@ const version = "__VERSION__";
 
 function loadCoreSdkScript(options: LoadCoreSdkScriptOptions = {}) {
     validateArguments(options);
+    const isServerEnv = isServer();
+
+    // SSR safeguard - warn about incorrect usage
+    if (isServerEnv) {
+        console.warn(
+            "PayPal JS: loadCoreSdkScript() was called on the server. This function should only be called on the client side. Please ensure you're not calling this during server-side rendering.",
+        );
+        return Promise.resolve(null);
+    }
+
     const { environment, debug } = options;
 
     const baseURL =

packages/paypal-js/types/v6/index.d.ts

@@ -146,7 +146,7 @@ export type LoadCoreSdkScriptOptions = {
 
 export function loadCoreSdkScript(
     options: LoadCoreSdkScriptOptions,
-): Promise<PayPalV6Namespace>;
+): Promise<PayPalV6Namespace | null>;
 
 // Components
 export * from "./components/paypal-payments";

packages/react-paypal-js/package.json

@@ -58,7 +58,8 @@
     "homepage": "https://paypal.github.io/react-paypal-js/",
     "dependencies": {
         "@paypal/paypal-js": "^9.0.0",
-        "@paypal/sdk-constants": "^1.0.122"
+        "@paypal/sdk-constants": "^1.0.122",
+        "dequal": "^2.0.3"
     },
     "devDependencies": {
         "@babel/core": "^7.17.5",
@@ -124,7 +125,10 @@
         ],
         "setupFilesAfterEnv": [
             "./jest.setup.ts"
-        ]
+        ],
+        "moduleNameMapper": {
+            "@paypal/paypal-js/sdk-v6": "<rootDir>/../../node_modules/@paypal/paypal-js/dist/v6/esm/paypal-js.js"
+        }
     },
     "bugs": {
         "url": "https://github.com/paypal/react-paypal-js/issues"

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

@@ -0,0 +1,242 @@
+/**
+ * @jest-environment node
+ */
+
+import React from "react";
+import { renderToString } from "react-dom/server";
+import { loadCoreSdkScript } from "@paypal/paypal-js/sdk-v6";
+
+import { PayPalProvider } from "./PayPalProvider";
+import { usePayPal } from "../hooks/usePayPal";
+import { INSTANCE_LOADING_STATE } from "../types/PayPalProviderTypes";
+import { isServer } from "../utils";
+import { TEST_CLIENT_TOKEN, expectInitialState } from "./providerTestUtils";
+
+import type {
+    CreateInstanceOptions,
+    PayPalContextState,
+    LoadCoreSdkScriptOptions,
+} from "../types";
+
+jest.mock("@paypal/paypal-js/sdk-v6", () => ({
+    loadCoreSdkScript: jest.fn(),
+}));
+
+jest.mock("../utils", () => ({
+    ...jest.requireActual("../utils"),
+    isServer: () => true,
+}));
+
+const createInstanceOptions: CreateInstanceOptions<["paypal-payments"]> = {
+    components: ["paypal-payments"],
+    clientToken: TEST_CLIENT_TOKEN,
+};
+
+const scriptOptions: LoadCoreSdkScriptOptions = {
+    environment: "sandbox",
+};
+
+// Test utilities
+function renderSSRProvider(
+    instanceOptions = createInstanceOptions,
+    scriptOpts = scriptOptions,
+    children?: React.ReactNode,
+) {
+    const { state, TestComponent } = setupSSRTestComponent();
+    const { components, clientToken } = instanceOptions;
+
+    const html = renderToString(
+        <PayPalProvider
+            components={components}
+            clientToken={clientToken}
+            scriptOptions={scriptOpts}
+        >
+            <TestComponent>{children}</TestComponent>
+        </PayPalProvider>,
+    );
+
+    return { html, state };
+}
+
+describe("PayPalProvider SSR", () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    test("should verify isServer mock is working", () => {
+        expect(isServer()).toBe(true);
+    });
+
+    test("should initialize correctly and never load scripts during SSR", () => {
+        const { state } = renderSSRProvider();
+
+        expectInitialState(state);
+        expect(loadCoreSdkScript).not.toHaveBeenCalled();
+    });
+
+    describe("Server-Side Rendering", () => {
+        test("should not attempt DOM access during server rendering", () => {
+            // In Node environment, document should be undefined
+            expect(typeof document).toBe("undefined");
+
+            expect(() => renderSSRProvider()).not.toThrow();
+        });
+
+        test("should maintain state consistency across multiple server renders", () => {
+            const { html: html1, state: state1 } = renderSSRProvider();
+            const { html: html2, state: state2 } = renderSSRProvider();
+
+            // Both renders should produce identical state and HTML
+            expectInitialState(state1);
+            expectInitialState(state2);
+            expect(html1).toBe(html2);
+        });
+    });
+
+    describe("Hydration Preparation", () => {
+        test("should prepare serializable state for client hydration", () => {
+            const { state } = renderSSRProvider();
+
+            // Server state should be safe for serialization
+            const serializedState = JSON.stringify({
+                loadingStatus: state.loadingStatus,
+                sdkInstance: state.sdkInstance,
+                eligiblePaymentMethods: state.eligiblePaymentMethods,
+                error: state.error,
+            });
+
+            expect(() => JSON.parse(serializedState)).not.toThrow();
+
+            const parsedState = JSON.parse(serializedState);
+            expectInitialState(parsedState);
+        });
+
+        test("should handle different options consistently", () => {
+            const updatedOptions = {
+                ...createInstanceOptions,
+                clientToken: "updated-token",
+            };
+
+            const { state: state1 } = renderSSRProvider();
+            const { state: state2 } = renderSSRProvider(updatedOptions);
+
+            // Both should have consistent initial state regardless of options
+            expectInitialState(state1);
+            expectInitialState(state2);
+            expect(loadCoreSdkScript).not.toHaveBeenCalled();
+        });
+    });
+
+    describe("React SSR Integration", () => {
+        test("should render without warnings or errors", () => {
+            const consoleSpy = jest
+                .spyOn(console, "error")
+                .mockImplementation();
+
+            const { html } = renderSSRProvider(
+                createInstanceOptions,
+                scriptOptions,
+                <div>SSR Content</div>,
+            );
+
+            expect(consoleSpy).not.toHaveBeenCalled();
+            expect(html).toBeTruthy();
+            expect(typeof html).toBe("string");
+            expect(html).toContain("SSR Content");
+
+            consoleSpy.mockRestore();
+        });
+
+        test("should handle complex options without issues", () => {
+            const complexOptions: CreateInstanceOptions<
+                ["paypal-payments", "venmo-payments"]
+            > = {
+                components: ["paypal-payments", "venmo-payments"],
+                clientToken: "complex-token-123",
+                locale: "en_US",
+                pageType: "checkout",
+                partnerAttributionId: "test-partner",
+            };
+
+            const { html } = renderSSRProvider(
+                // @ts-expect-error renderSSRProvider is typed for single component
+                complexOptions,
+                { environment: "production", debug: true },
+                <div>Complex Options Test</div>,
+            );
+
+            expect(html).toBeTruthy();
+            expect(html).toContain("Complex Options Test");
+        });
+
+        test("should generate consistent HTML across renders", () => {
+            const { html: html1 } = renderSSRProvider(
+                createInstanceOptions,
+                scriptOptions,
+                <div data-testid="ssr-content">Test Content</div>,
+            );
+            const { html: html2 } = renderSSRProvider(
+                createInstanceOptions,
+                scriptOptions,
+                <div data-testid="ssr-content">Test Content</div>,
+            );
+
+            expect(html1).toBe(html2);
+            expect(html1).toContain('data-testid="ssr-content"');
+        });
+    });
+
+    describe("Multiple Renders", () => {
+        test("should handle multiple renders without side effects", () => {
+            // Multiple renders should not cause issues
+            expect(() => {
+                for (let i = 0; i < 5; i++) {
+                    renderSSRProvider({
+                        ...createInstanceOptions,
+                        clientToken: `token-${i}`,
+                    });
+                }
+            }).not.toThrow();
+
+            // Should never attempt to load scripts regardless of render count
+            expect(loadCoreSdkScript).not.toHaveBeenCalled();
+        });
+    });
+});
+
+describe("usePayPalInstance SSR", () => {
+    test("should work correctly in SSR context", () => {
+        const { state } = renderSSRProvider();
+
+        expectInitialState(state);
+    });
+});
+
+function setupSSRTestComponent() {
+    const state: PayPalContextState = {
+        loadingStatus: INSTANCE_LOADING_STATE.INITIAL,
+        sdkInstance: null,
+        eligiblePaymentMethods: null,
+        error: null,
+        dispatch: jest.fn(),
+    };
+
+    function TestComponent({
+        children = null,
+    }: {
+        children?: React.ReactNode;
+    }) {
+        try {
+            const instanceState = usePayPal();
+            Object.assign(state, instanceState);
+        } catch (error) {
+            state.error = error as Error;
+        }
+        return <>{children}</>;
+    }
+
+    return {
+        state,
+        TestComponent,
+    };
+}