Skip to content

Commit 630f848

Browse files
SwiftworkSwiftwork
committed
docs: update readmes
1 parent 59ee8dc commit 630f848

2 files changed

Lines changed: 179 additions & 36 deletions

File tree

‎packages/react-sdk/README.md‎

Lines changed: 86 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,10 @@ import { ReflagProvider } from "@reflag/react-sdk";
2727

2828
<ReflagProvider
2929
publishableKey="{YOUR_PUBLISHABLE_KEY}"
30-
company={{ id: "acme_inc", plan: "pro" }}
31-
user={{ id: "john doe" }}
30+
context={{
31+
company: { id: "acme_inc", plan: "pro" },
32+
user: { id: "john doe" },
33+
}}
3234
loadingComponent={<Loading />}
3335
>
3436
{/* children here are shown when loading finishes or immediately if no `loadingComponent` is given */}
@@ -90,35 +92,61 @@ function StartHuddleButton() {
9092

9193
`useFlag` can help you do much more. See a full example for `useFlag` [see below](#useflag).
9294

93-
## Setting `user` and `company`
95+
## Setting context
9496

95-
Reflag determines which flags are active for a given `user`, `company`, or `other`.
96-
You pass these to the `ReflagProvider` as props.
97+
Reflag determines which flags are active for a given `user`, `company`, or `other` context.
98+
You can pass these to the `ReflagProvider` using the `context` prop.
9799

98-
If you supply `user` or `company` objects, they must include at least the `id` property otherwise they will be ignored in their entirety.
99-
In addition to the `id`, you must also supply anything additional that you want to be able to evaluate flag targeting rules against.
100-
Attributes which are not properties of the `user` or `company` can be supplied using the `other` prop.
100+
### Using the `context` prop
101101

102-
Attributes cannot be nested (multiple levels) and must be either strings, numbers or booleans.
103-
A number of special attributes exist:
102+
```tsx
103+
<ReflagProvider
104+
publishableKey={YOUR_PUBLISHABLE_KEY}
105+
context={{
106+
user: { id: "user_123", name: "John Doe", email: "john@acme.com" },
107+
company: { id: "company_123", name: "Acme, Inc" },
108+
other: { source: "web" },
109+
}}
110+
>
111+
<LoadingReflag>
112+
{/* children here are shown when loading finishes */}
113+
</LoadingReflag>
114+
</ReflagProvider>
115+
```
104116

105-
- `name` -- display name for `user`/`company`,
106-
- `email` -- the email of the user,
107-
- `avatar` -- the URL for `user`/`company` avatar image.
117+
### Legacy individual props (deprecated)
118+
119+
For backward compatibility, you can still use individual props, but these are deprecated and will be removed in the next major version:
108120

109121
```tsx
110122
<ReflagProvider
111123
publishableKey={YOUR_PUBLISHABLE_KEY}
112124
user={{ id: "user_123", name: "John Doe", email: "john@acme.com" }}
113125
company={{ id: "company_123", name: "Acme, Inc" }}
114-
other={{ completedSteps: [1, 4, 7] }}
126+
otherContext={{ source: "web" }}
115127
>
116128
<LoadingReflag>
117129
{/* children here are shown when loading finishes */}
118130
</LoadingReflag>
119131
</ReflagProvider>
120132
```
121133

134+
> [!Important]
135+
> The `user`, `company`, and `otherContext` props are deprecated. Use the `context` prop instead, which provides the same functionality in a more structured way.
136+
137+
### Context requirements
138+
139+
If you supply `user` or `company` objects, they must include at least the `id` property otherwise they will be ignored in their entirety.
140+
In addition to the `id`, you must also supply anything additional that you want to be able to evaluate flag targeting rules against.
141+
Attributes which are not properties of the `user` or `company` can be supplied using the `other` property.
142+
143+
Attributes cannot be nested (multiple levels) and must be either strings, numbers or booleans.
144+
A number of special attributes exist:
145+
146+
- `name` -- display name for `user`/`company`,
147+
- `email` -- the email of the user,
148+
- `avatar` -- the URL for `user`/`company` avatar image.
149+
122150
To retrieve flags along with their targeting information, use `useFlag(key: string)` hook (described in a section below).
123151

124152
Note that accessing `isEnabled` on the object returned by `useFlag()` automatically
@@ -409,12 +437,53 @@ export function HuddleFeature() {
409437

410438
This App Router approach leverages Server Components for server-side flag fetching while using Client Components only where React state and hooks are needed.
411439

440+
## `<ReflagClientProvider>` component
441+
442+
The `<ReflagClientProvider>` is a lower-level component that accepts a pre-initialized `ReflagClient` instance. This is useful for advanced use cases where you need full control over client initialization or want to share a client instance across multiple parts of your application.
443+
444+
### Usage
445+
446+
```tsx
447+
import { ReflagClient } from "@reflag/browser-sdk";
448+
import { ReflagClientProvider } from "@reflag/react-sdk";
449+
450+
// Initialize the client yourself
451+
const client = new ReflagClient({
452+
publishableKey: "your-publishable-key",
453+
user: { id: "user123", name: "John Doe" },
454+
company: { id: "company456", name: "Acme Inc" },
455+
// ... other configuration options
456+
});
457+
458+
// Initialize the client
459+
await client.initialize();
460+
461+
function App() {
462+
return (
463+
<ReflagClientProvider client={client} loadingComponent={<Loading />}>
464+
<Router />
465+
</ReflagClientProvider>
466+
);
467+
}
468+
```
469+
470+
### Props
471+
472+
The `ReflagClientProvider` accepts the following props:
473+
474+
- `client`: A pre-initialized `ReflagClient` instance
475+
- `loadingComponent`: Optional React component to show while the client is initializing (same as `ReflagProvider`)
476+
477+
> [!Note]
478+
> Most applications should use `ReflagProvider` or `ReflagBootstrappedProvider` instead of `ReflagClientProvider`. Only use this component when you need the advanced control it provides.
479+
412480
## `<ReflagProvider>` component
413481

414482
The `<ReflagProvider>` initializes the Reflag SDK, fetches flags and starts listening for automated feedback survey events. The component can be configured using a number of props:
415483

416484
- `publishableKey` is used to connect the provider to an _environment_ on Reflag. Find your `publishableKey` under [environment settings](https://app.reflag.com/env-current/settings/app-environments) in Reflag,
417-
- `company`, `user` and `other` make up the _context_ that is used to determine if a flag is enabled or not. `company` and `user` contexts are automatically transmitted to Reflag servers so the Reflag app can show you which companies have access to which flags etc.
485+
- `context` (recommended): An object containing `user`, `company`, and `other` properties that make up the evaluation context used to determine if a flag is enabled or not. `company` and `user` contexts are automatically transmitted to Reflag servers so the Reflag app can show you which companies have access to which flags etc.
486+
- `company`, `user` and `other` (deprecated): Individual props for context. These are deprecated in favor of the `context` prop and will be removed in the next major version.
418487
> [!Note]
419488
> If you specify `company` and/or `user` they must have at least the `id` property, otherwise they will be ignored in their entirety. You should also supply anything additional you want to be able to evaluate flag targeting against,
420489
- `fallbackFlags`: A list of strings which specify which flags to consider enabled if the SDK is unable to fetch flags. Can be provided in two formats:
@@ -476,7 +545,7 @@ The `<ReflagBootstrappedProvider>` is a specialized version of the `ReflagProvid
476545
The component accepts the following props:
477546
478547
- `flags`: Pre-fetched flags data of type `BootstrappedFlags` obtained from the Node SDK's `getFlagsForBootstrap()` method. This contains both the context (user, company, other) and the flags data.
479-
- All other props available in [`ReflagProvider`](#reflagprovider-component) are supported except `user`, `company`, and `other` (which are extracted from `flags.context`).
548+
- All other props available in [`ReflagProvider`](#reflagprovider-component) are supported except `context`, `user`, `company`, and `other` (which are extracted from `flags.context`).
480549
481550
**Example:**
482551
@@ -505,7 +574,7 @@ function App({ bootstrapData }: AppProps) {
505574
```
506575
507576
> [!Note]
508-
> When using `ReflagBootstrappedProvider`, the user, company, and other are extracted from the `flags.context` property and don't need to be passed separately.
577+
> When using `ReflagBootstrappedProvider`, the context (user, company, and other) is extracted from the `flags.context` property and doesn't need to be passed separately.
509578
510579
## Hooks
511580
@@ -682,8 +751,6 @@ function FlagOptIn() {
682751
}
683752
```
684753
685-
Note: To change the `user.id` or `company.id`, you need to update the props passed to `ReflagProvider` instead of using these hooks.
686-
687754
### `useClient()`
688755
689756
Returns the `ReflagClient` used by the `ReflagProvider`. The client offers more functionality that

‎packages/vue-sdk/README.md‎

Lines changed: 93 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,11 @@ Finally, if you have customized the look & feel of the Feedback component, updat
4242

4343
## Get started
4444

45-
### 1. Wrap your application with the `ReflagProvider`
45+
### 1. Add the `ReflagProvider` context provider
46+
47+
Add the `ReflagProvider` context provider to your application:
48+
49+
**Example:**
4650

4751
```vue
4852
<script setup lang="ts">
@@ -51,8 +55,10 @@ import { ReflagProvider } from "@reflag/vue-sdk";
5155
5256
<ReflagProvider
5357
:publishable-key="publishableKey"
54-
:user="{ id: 'user_123', name: 'John Doe', email: 'john@acme.com' }"
55-
:company="{ id: 'acme_inc', plan: 'pro' }"
58+
:context="{
59+
user: { id: 'user_123', name: 'John Doe', email: 'john@acme.com' },
60+
company: { id: 'acme_inc', plan: 'pro' },
61+
}"
5662
>
5763
<!-- your app -->
5864
</ReflagProvider>
@@ -78,32 +84,57 @@ const { isEnabled } = useFlag("huddles");
7884

7985
See [useFlag()](#useflag) for a full example
8086

81-
## Setting `user` and `company`
87+
## Setting context
8288

83-
Reflag determines which flags are active for a given `user`, `company`, or `otherContext`.
84-
You pass these to the `ReflagProvider` as props.
89+
Reflag determines which flags are active for a given `user`, `company`, or `other` context.
90+
You can pass these to the `ReflagProvider` using the `context` prop.
8591

86-
If you supply `user` or `company` objects, they must include at least the `id` property otherwise they will be ignored in their entirety.
87-
In addition to the `id`, you must also supply anything additional that you want to be able to evaluate flag targeting rules against.
88-
Attributes which are not properties of the `user` or `company` can be supplied using the `otherContext` prop.
92+
### Using the `context` prop
8993

90-
Attributes cannot be nested (multiple levels) and must be either strings, numbers or booleans.
91-
A number of special attributes exist:
94+
```vue
95+
<ReflagProvider
96+
:publishable-key="publishableKey"
97+
:context="{
98+
user: { id: 'user_123', name: 'John Doe', email: 'john@acme.com' },
99+
company: { id: 'acme_inc', plan: 'pro' },
100+
other: { source: 'web' },
101+
}"
102+
>
103+
<!-- your app -->
104+
</ReflagProvider>
105+
```
92106

93-
- `name` -- display name for `user`/`company`,
94-
- `email` -- the email of the user,
95-
- `avatar` -- the URL for `user`/`company` avatar image.
107+
### Legacy individual props (deprecated)
108+
109+
For backward compatibility, you can still use individual props, but these are deprecated and will be removed in the next major version:
96110

97111
```vue
98112
<ReflagProvider
99113
:publishable-key="publishableKey"
100114
:user="{ id: 'user_123', name: 'John Doe', email: 'john@acme.com' }"
101115
:company="{ id: 'acme_inc', plan: 'pro' }"
116+
:other-context="{ source: 'web' }"
102117
>
103118
<!-- your app -->
104119
</ReflagProvider>
105120
```
106121

122+
> [!Important]
123+
> The `user`, `company`, and `otherContext` props are deprecated. Use the `context` prop instead, which provides the same functionality in a more structured way.
124+
125+
### Context requirements
126+
127+
If you supply `user` or `company` objects, they must include at least the `id` property otherwise they will be ignored in their entirety.
128+
In addition to the `id`, you must also supply anything additional that you want to be able to evaluate flag targeting rules against.
129+
Attributes which are not properties of the `user` or `company` can be supplied using the `other` property.
130+
131+
Attributes cannot be nested (multiple levels) and must be either strings, numbers or booleans.
132+
A number of special attributes exist:
133+
134+
- `name` -- display name for `user`/`company`,
135+
- `email` -- the email of the user,
136+
- `avatar` -- the URL for `user`/`company` avatar image.
137+
107138
To retrieve flags along with their targeting information, use `useFlag(key: string)` hook (described in a section below).
108139

109140
Note that accessing `isEnabled` on the object returned by `useFlag()` automatically
@@ -139,7 +170,8 @@ generates a `check` event.
139170
The `<ReflagProvider>` initializes the Reflag SDK, fetches flags and starts listening for automated feedback survey events. The component can be configured using a number of props:
140171

141172
- `publishableKey` is used to connect the provider to an _environment_ on Reflag. Find your `publishableKey` under [environment settings](https://app.reflag.com/env-current/settings/app-environments) in Reflag,
142-
- `company`, `user` and `otherContext` make up the _context_ that is used to determine if a flag is enabled or not. `company` and `user` contexts are automatically transmitted to Reflag servers so the Reflag app can show you which companies have access to which flags etc.
173+
- `context`: An object containing `user`, `company`, and `other` properties that make up the evaluation context used to determine if a flag is enabled or not. `company` and `user` contexts are automatically transmitted to Reflag servers so the Reflag app can show you which companies have access to which flags etc.
174+
- `company`, `user` and `otherContext` (deprecated): Individual props for context. These are deprecated in favor of the `context` prop and will be removed in the next major version.
143175

144176
> [!Note]
145177
> If you specify `company` and/or `user` they must have at least the `id` property, otherwise they will be ignored in their entirety. You should also supply anything additional you want to be able to evaluate flag targeting against,
@@ -238,15 +270,59 @@ const bootstrappedFlags = client.getFlagsForBootstrap(context);
238270
// Pass to your Vue app
239271
```
240272

241-
### Props
273+
### ReflagBootstrappedProvider Props
242274

243275
`ReflagBootstrappedProvider` accepts all the same props as `ReflagProvider` except:
244276

245-
- `timeoutMs`, `staleWhileRevalidate`, `staleTimeMs`, `expireTimeMs` are not applicable since no requests to fetch flags are made
246277
- `flags`: The pre-fetched flags object containing context and flag data
278+
- All other props available in `ReflagProvider` are supported except `context`, `user`, `company`, and `otherContext` (which are extracted from `flags.context`)
247279

248280
If the `flags` prop is not provided or is undefined, the provider will not initialize the client and will render in a non-loading state.
249281

282+
## `<ReflagClientProvider>` component
283+
284+
The `<ReflagClientProvider>` is a lower-level component that accepts a pre-initialized `ReflagClient` instance. This is useful for advanced use cases where you need full control over client initialization or want to share a client instance across multiple parts of your application.
285+
286+
### ReflagClientProvider Usage
287+
288+
```vue
289+
<script setup lang="ts">
290+
import { ReflagClient } from "@reflag/browser-sdk";
291+
import { ReflagClientProvider } from "@reflag/vue-sdk";
292+
293+
// Initialize the client yourself
294+
const client = new ReflagClient({
295+
publishableKey: "your-publishable-key",
296+
user: { id: "user123", name: "John Doe" },
297+
company: { id: "company456", name: "Acme Inc" },
298+
// ... other configuration options
299+
});
300+
301+
// Initialize the client
302+
await client.initialize();
303+
</script>
304+
305+
<template>
306+
<ReflagClientProvider :client="client">
307+
<template #loading>Loading...</template>
308+
<Router />
309+
</ReflagClientProvider>
310+
</template>
311+
```
312+
313+
### ReflagClientProvider Props
314+
315+
The `ReflagClientProvider` accepts the following props:
316+
317+
- `client`: A pre-initialized `ReflagClient` instance
318+
319+
### Slots
320+
321+
- `loading`: Optional slot to show while the client is initializing (same as `ReflagProvider`)
322+
323+
> [!Note]
324+
> Most applications should use `ReflagProvider` or `ReflagBootstrappedProvider` instead of `ReflagClientProvider`. Only use this component when you need the advanced control it provides.
325+
250326
## Hooks
251327

252328
### `useFlag()`

0 commit comments

Comments
 (0)