[REACT-SDK] add multiprovider support (#494)

* reactSdk: multiprovider support * Update website/docs/sdk-reference/react.mdx Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> * Update website/docs/sdk-reference/react.mdx Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> * Update website/docs/sdk-reference/react.mdx Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> * Update website/versioned_docs/version-V1/sdk-reference/react.mdx Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> * Update website/versioned_docs/version-V1/sdk-reference/react.mdx Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> * Update website/versioned_docs/version-V1/sdk-reference/react.mdx Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> * Update website/versioned_docs/version-V1/sdk-reference/react.mdx Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> * Update website/versioned_docs/version-V1/sdk-reference/react.mdx Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> * Update website/docs/sdk-reference/react.mdx Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> * fixup! Update website/docs/sdk-reference/react.mdx * fixup! Update website/docs/sdk-reference/react.mdx * Update website/docs/sdk-reference/react.mdx Co-authored-by: adams85 <31276480+adams85@users.noreply.github.com> * fixup! Update website/docs/sdk-reference/react.mdx --------- Co-authored-by: andrew-cat <endre.toth@configcat.com> Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> Co-authored-by: adams85 <31276480+adams85@users.noreply.github.com>
configcat · Oct 16, 2024 · 1dfa106 · 1dfa106
1 parent bed1d50
commit 1dfa106
Showing 1 changed file with 55 additions and 0 deletions.
diff --git a/website/docs/sdk-reference/react.mdx b/website/docs/sdk-reference/react.mdx
@@ -131,6 +131,7 @@ _ConfigCat Client_ is responsible for:
 | `sdkKey`      | **REQUIRED.** SDK Key to access your feature flags and configurations. Get it from _ConfigCat Dashboard_.                               | -                      |
 | `pollingMode` | Optional. The polling mode to use to acquire the setting values from the ConfigCat servers. [More about polling modes](#polling-modes). | `PollingMode.AutoPoll` |
 | `options`     | Optional. The options object. See the table below.                                                                                      | -                      |
+| `id`          | Optional. Instructs the ConfigCat Client to use a specific `ConfigCatProvider` instead of the default one. Use it if you have multiple `ConfigCatProvider`s in your code. [More about multiple providers](#using-multiple-providers).                                  | `undefined` (none)     |
 
 The available options depends on the chosen polling mode. However, there are some common options which can be set in the case of every polling mode:
 
@@ -176,6 +177,7 @@ The SDK supports two ways to acquire the initialized ConfigCat instance:
 | `key`          | **REQUIRED.** Setting-specific key. Set on _ConfigCat Dashboard_ for each setting.                                         |
 | `defaultValue` | **REQUIRED.** This value will be returned in case of an error.                                                             |
 | `user`         | Optional, _User Object_. Essential when using Targeting. [Read more about Targeting.](../targeting/targeting-overview.mdx) |
+| `providerId`   | Optional. Instructs the ConfigCat Client to use a specific `ConfigCatProvider` instead of the default one. Use it if you have multiple `ConfigCatProvider`s in your code. [More about multiple providers](#using-multiple-providers).                   |
 
 ```tsx
 function ButtonComponent() {
@@ -220,6 +222,10 @@ If you specify an allowed type but it mismatches the setting kind, an error mess
 
 ## Anatomy of `useConfigCatClient()`
 
+| Parameters     | Description                                                                                                                |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `providerId`   | Optional. Instructs the ConfigCat Client to use a specific `ConfigCatProvider` instead of the default one. Use it if you have multiple `ConfigCatProvider`s in your code. [More about multiple providers](#using-multiple-providers).                   |
+
 This custom hook returns the ConfigCat instance from the context API. You have to wrap your parent element with `ConfigCatProvider` to ensure a `ConfigCatContextData`.
 
 ```tsx
@@ -243,6 +249,10 @@ export const FlagDetailsComponent = () => {
 
 ## Anatomy of `withConfigCatClient()`
 
+| Parameters     | Description                                                                                                                |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `providerId`   | Optional. Instructs the ConfigCat Client to use a specific `ConfigCatProvider` instead of the default one. Use it if you have multiple `ConfigCatProvider`s in your code. [More about multiple providers](#using-multiple-providers).                   |
+
 This is a higher-order component that can take your React component and will return the component with the injected ConfigCat related props (`WithConfigCatClientProps`).
 
 These props are the following:
@@ -977,6 +987,51 @@ If you do not want to expose the SDK key or the content of the config JSON file,
 
 Also, we recommend using [confidential targeting comparators](../targeting/targeting-rule/user-condition.mdx#confidential-text-comparators) in the Targeting Rules of those feature flags that are used in the frontend/mobile SDKs.
 
+## Using multiple providers
+
+`ConfigCatProvider` allows you to access the feature flags of a specific Config, identified by the `sdkKey` parameter. (More precisely, `sdkKey` identifies a combination of a Config and an Environment.)
+
+However, in some cases, you may want to access feature flags from multiple Configs in your application. To do this, you will need to use multiple `ConfigCatProvider`s — each associated with a specific Config by providing the corresponding `sdkKey`.
+
+It's also important to keep in mind that `useFeatureFlag` calls will default to using the nearest `ConfigCatProvider`, similar to how React's [useContext](https://react.dev/learn/passing-data-deeply-with-context) works.
+
+So, when working with multiple providers, it may be necessary to differentiate between them. You can achieve this by assigning a unique `id` to each provider. (Note that the absence of `id` also acts as a unique identifier.)
+
+Then, by passing the provider id in your `useFeatureFlag`, `useConfigCatClient`, or similar calls, you can explicitly specify which provider (i.e. which `sdkKey`, and ultimately which Config and Environment) to use.
+
+```tsx
+const CC_PROVIDER_ID_COMMON = "COMMON";
+const CC_PROVIDER_ID_FRONTEND = "FRONTEND";
+
+<ConfigCatProvider sdkKey="#YOUR_COMMON_SDK_KEY#" id={CC_PROVIDER_ID_COMMON}> 
+  <ConfigCatProvider sdkKey="#YOUR_FRONTEND_SDK_KEY#" id={CC_PROVIDER_ID_FRONTEND}>
+      ...
+      const myFeatureInCommon = useFeatureFlag("myFeatureInCommon", false, void 0, CC_PROVIDER_ID_COMMON)
+
+      const myFeatureInFrontEnd = useFeatureFlag("myFeatureInFrontEnd", false, void 0, CC_PROVIDER_ID_FRONTEND)
+      ...
+  </ConfigCatProvider>
+</ConfigCatProvider>
+```
+
+When you are using multiple providers and they are not nested, it is not necessary to specify the `id` attribute:
+
+```tsx
+<ConfigCatProvider sdkKey="#YOUR_COMMON_SDK_KEY#">
+  ...
+  const myFeatureInCommon = useFeatureFlag("myFeatureInCommon", false);
+  ...
+</ConfigCatProvider>
+
+<ConfigCatProvider sdkKey="#YOUR_FRONTEND_SDK_KEY#">
+  ...
+  const myFeatureInFrontEnd = useFeatureFlag("myFeatureInFrontEnd", false);
+  ...
+</ConfigCatProvider>
+```
+
+If you are using higher order components, you can set the `providerId` parameter in the `withConfigCatClient` function.
+
 ## Sample Application
 
 - <a