You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
We’re excited to hear your thoughts on your developer experience with PWA Kit and the Composable Storefront generally! Your feedback is incredibly valuable in helping us guide our roadmap and improve our offering.
3
+
We're excited to hear your thoughts on your developer experience with PWA Kit and the Composable Storefront generally! Your feedback is incredibly valuable in helping us guide our roadmap and improve our offering.
4
4
5
5
:clipboard: Take our quick survey here: [Survey](https://forms.gle/bUZNxQ3QKUcrjhV18)
## Advanced: Customizing SDK Clients with `transformSDKClient`
487
+
488
+
To support advanced use cases, such as integrating with older templates or customizing API client behavior, `commerce-sdk-react` provides a utility called `transformSDKClient`. This utility wraps any Commerce SDK client instance in a JavaScript Proxy, enabling you to intercept and transform method arguments, headers, parameters, and other options before each SDK call is made.
489
+
490
+
This is especially useful for:
491
+
- Adapting SDK clients for legacy or custom templates.
492
+
- Removing references to unused SDK clients.
493
+
494
+
### How It Works
495
+
496
+
`transformSDKClient` takes an SDK client instance and a configuration object. The configuration can include:
497
+
- `props`: Arbitrary props you want to pass to your transformer.
498
+
- `transformer`: A function that receives the props, method name, and options, and returns the transformed options.
499
+
- `onError`: (Optional) A function to handle errors thrown by SDK methods.
500
+
501
+
Every method call on the proxied client passes through your transformer before being executed.
502
+
503
+
#### Example: Passing Custom SDK Clients to the Provider
504
+
505
+
You can use this utility to pass in your own SDK clients to the `CommerceApiProvider` via the `apiClients` prop, and apply custom transformations globally.
// You can also pass custom headers, fetchOptions, etc.
527
+
>
528
+
{children}
529
+
</CommerceApiProvider>
530
+
)
531
+
```
532
+
533
+
> **Note:** The `CommerceApiProvider` will automatically wrap each client in `apiClients` with `transformSDKClient`, using a default transformer that injects headers and fetch options from the provider props. You must use props passed to `CommerceApiProvider` for setting custom headers and fetch options. `transformSDKClient` merges headers and options passed in as props with the default values.
- **props**: Any extra data you want to pass to your transformer.
551
+
- **transformer**: Function to transform method arguments before each SDK call.
552
+
- **onError**: (Optional) Function to handle errors from SDK methods.
553
+
554
+
555
+
> **Note:** If you choose to pass the `apiClients` prop, you are responsible for providing all SDK clients you intend to use in your application. Any hooks or features that rely on a missing client will throw an error at runtime. This allows for customization, but requires you to explicitly include each client you need.
556
+
557
+
### Handling Missing SDK Clients
558
+
559
+
With the introduction of the optional `apiClients` prop and support for custom SDK client injection, `commerce-sdk-react` now provides robust error handling for missing clients. If you attempt to use a query or mutation hook for a client that was not initialized or passed to the `CommerceApiProvider`, a clear error will be thrown.
560
+
561
+
For example, if you call a hook like `useShopperProducts` but did not provide a `shopperProducts` client in your `apiClients` prop, you will see an error message similar to this error.
562
+
563
+
```text
564
+
Missing required client:shopperProducts. Please initialize shopperProducts classand provide it in CommerceApiProvider's apiClients prop.
565
+
```
566
+
567
+
This ensures that your application fails fast and provides actionable feedback, making it easier to debug configuration issues—especially when integrating with older templates or customizing your SDK client setup.
568
+
569
+
### Disabling Automatic Auth Initialization
570
+
571
+
By default, `CommerceApiProvider` automatically initializes authentication by calling `auth.ready()` as soon as the provider renders. This is the standard and recommended behavior for most applications.
572
+
573
+
**New in v3.4.0:** You can now optionally disable this automatic initialization by passing the `disableAuthInit` prop:
574
+
575
+
```jsx
576
+
<CommerceApiProvider
577
+
// ...other required props
578
+
disableAuthInit={true}
579
+
>
580
+
{children}
581
+
</CommerceApiProvider>
582
+
```
583
+
584
+
- **Default:** `disableAuthInit` is `false` (auth is initialized automatically).
585
+
- **When to use:** Set `disableAuthInit` to `true` if you are initializing authentication outside of the provider (for example, in legacy PWA Kit templates or when using SSR with `getProps`). This prevents duplicate initialization and potential issues with tokens or customer information.
586
+
587
+
> **Note:** For most modern PWA Kit and React Query-based apps, you do **not** need to set this prop.
0 commit comments