Skip to content

Commit 5852feb

Browse files
adams85adams85
authored
Add docs on how to use ConfigCat with some OpenFeature SDKs (#548)
* Add docs on how to use ConfigCat with the OpenFeature React SDK * Add docs on how to use ConfigCat with the OpenFeature Angular SDK * Add docs on how to use ConfigCat with the OpenFeature NestJS SDK * Update overview provider list
1 parent abdaa72 commit 5852feb

File tree

14 files changed

+742
-4
lines changed

14 files changed

+742
-4
lines changed

‎website/docs/sdk-reference/openfeature/angular.mdx

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
id: angular
3+
title: Using ConfigCat's OpenFeature Provider in Angular
4+
description: This is a step-by-step guide on how to use ConfigCat with the OpenFeature Angular SDK.
5+
---
6+
7+
import Tabs from '@theme/Tabs';
8+
import TabItem from '@theme/TabItem';
9+
10+
## Getting started
11+
12+
OpenFeature offers an [Angular SDK](https://github.com/open-feature/js-sdk/tree/main/packages/angular) to streamline the use
13+
of OpenFeature in Angular applications. This SDK is built on top of the [OpenFeature JavaScript Web SDK](https://github.com/open-feature/js-sdk/blob/main/packages/web).
14+
15+
Since ConfigCat implements [a provider](./js.mdx) for the Web SDK, you can use ConfigCat with the OpenFeature Angular SDK,
16+
as explained below.
17+
18+
### 1. Install the Angular SDK and the ConfigCat provider
19+
20+
```bash
21+
npm i @openfeature/angular-sdk @openfeature/config-cat-web-provider
22+
```
23+
24+
### 2. Initialize the Angular SDK
25+
26+
The `ConfigCatWebProvider.create()` function takes the SDK key and an optional `options` argument containing additional
27+
configuration options for the underlying [ConfigCat client](../../js#creating-the-configcat-client):
28+
29+
* For applications using modules:
30+
31+
```ts
32+
import { NgModule } from '@angular/core';
33+
import { BooleanFeatureFlagDirective, type EvaluationContext, OpenFeatureModule } from '@openfeature/angular-sdk';
34+
import { ConfigCatWebProvider } from '@openfeature/config-cat-web-provider';
35+
import { createConsoleLogger, LogLevel } from 'configcat-js-ssr';
36+
37+
const configCatProvider = ConfigCatWebProvider.create('#YOUR-SDK-KEY#', {
38+
// Specify options for the underlying ConfigCat client
39+
logger: createConsoleLogger(LogLevel.Info),
40+
setupHooks: (hooks) => hooks.on('clientReady', () => console.log('Client is ready!')),
41+
// ...
42+
});
43+
44+
// Set the initial context for your evaluations
45+
const initialContext: EvaluationContext = {
46+
targetingKey: 'user-1',
47+
admin: false
48+
};
49+
50+
@NgModule({
51+
declarations: [
52+
// ...
53+
],
54+
imports: [
55+
// ...
56+
OpenFeatureModule.forRoot({
57+
provider: configCatProvider,
58+
context: initialContext
59+
}),
60+
// Alternatively, you can import the directive directly in your components
61+
BooleanFeatureFlagDirective
62+
],
63+
exports: [
64+
// Not needed if you import the directive directly in your components
65+
BooleanFeatureFlagDirective
66+
],
67+
bootstrap: [/* ... */]
68+
})
69+
export class AppModule { }
70+
```
71+
72+
* For applications using standalone components:
73+
74+
```ts
75+
import { type ApplicationConfig, importProvidersFrom } from '@angular/core';
76+
import { type EvaluationContext, OpenFeatureModule } from '@openfeature/angular-sdk';
77+
import { ConfigCatWebProvider } from '@openfeature/config-cat-web-provider';
78+
import { createConsoleLogger, LogLevel } from 'configcat-js-ssr';
79+
80+
const configCatProvider = ConfigCatWebProvider.create('#YOUR-SDK-KEY#', {
81+
// Specify options for the underlying ConfigCat client
82+
logger: createConsoleLogger(LogLevel.Info),
83+
setupHooks: (hooks) => hooks.on('clientReady', () => console.log('Client is ready!')),
84+
// ...
85+
});
86+
87+
// Set the initial context for your evaluations
88+
const initialContext: EvaluationContext = {
89+
targetingKey: 'user-1',
90+
admin: false
91+
};
92+
93+
export const appConfig: ApplicationConfig = {
94+
providers: [
95+
// ...
96+
importProvidersFrom(
97+
OpenFeatureModule.forRoot({
98+
provider: configCatProvider,
99+
context: initialContext
100+
})
101+
)
102+
]
103+
};
104+
```
105+
106+
### 3. Use your feature flag
107+
108+
```html
109+
<div
110+
*booleanFeatureFlag="'isAwesomeFeatureEnabled'; default: false; else: booleanFeatureElse; initializing: booleanFeatureInitializing; reconciling: booleanFeatureReconciling">
111+
This is shown when the feature flag is enabled.
112+
</div>
113+
<ng-template #booleanFeatureElse>
114+
This is shown when the feature flag is disabled.
115+
</ng-template>
116+
<ng-template #booleanFeatureInitializing>
117+
This is shown when the feature flag is initializing.
118+
</ng-template>
119+
<ng-template #booleanFeatureReconciling>
120+
This is shown when the feature flag is reconciling.
121+
</ng-template>
122+
```
123+
124+
## Evaluation Context
125+
126+
An <a href="https://openfeature.dev/docs/reference/concepts/evaluation-context" target="_blank">evaluation context</a>
127+
in the OpenFeature specification is a container for arbitrary contextual data that can be used as a basis for feature
128+
flag evaluation.
129+
130+
You can find [here](./js.mdx#evaluation-context) how the ConfigCat provider translates these evaluation contexts to
131+
ConfigCat [User Objects](../../js/#user-object).
132+
133+
## Advanced features
134+
135+
Read the documentation of the [OpenFeature Angular SDK](https://openfeature.dev/docs/reference/technologies/client/web/angular/)
136+
to learn more about the advanced capabilities of the SDK.
137+
138+
## Look under the hood
139+
140+
- <a href="https://github.com/open-feature/js-sdk-contrib/tree/main/libs/providers/config-cat-web" target="_blank">ConfigCat OpenFeature Provider's repository on GitHub</a>
141+
- <a href="https://www.npmjs.com/package/@openfeature/config-cat-web-provider" target="_blank">ConfigCat OpenFeature Provider in NPM</a>

‎website/docs/sdk-reference/openfeature/js.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ if (isAwesomeFeatureEnabled) {
5757

5858
On application shutdown, clean up the OpenFeature provider and the underlying ConfigCat client.
5959

60-
```cs
60+
```js
6161
await OpenFeature.clearProviders();
6262
```
6363

‎website/docs/sdk-reference/openfeature/nestjs.mdx

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
id: nestjs
3+
title: Using ConfigCat's OpenFeature Provider in NestJS
4+
description: This is a step-by-step guide on how to use ConfigCat with the OpenFeature NestJS SDK.
5+
---
6+
7+
import Tabs from '@theme/Tabs';
8+
import TabItem from '@theme/TabItem';
9+
10+
## Getting started
11+
12+
OpenFeature offers a [NestJS SDK](https://github.com/open-feature/js-sdk/tree/main/packages/nest) to streamline the use
13+
of OpenFeature in NestJS applications. This SDK is built on top of the [OpenFeature JavaScript Node.js SDK](https://github.com/open-feature/js-sdk/blob/main/packages/server).
14+
15+
Since ConfigCat implements [a provider](./node.mdx) for the Node.js SDK, you can use ConfigCat with the OpenFeature NestJS SDK,
16+
as explained below.
17+
18+
### 1. Install the NestJS SDK and the ConfigCat provider
19+
20+
```bash
21+
npm i @openfeature/nestjs-sdk @openfeature/config-cat-provider
22+
```
23+
24+
### 2. Initialize the NestJS SDK
25+
26+
The `ConfigCatProvider.create()` function takes the SDK key, the desired [polling mode](../../node#polling-modes)
27+
(Auto Polling is recommended for this kind of application) and an optional `options` argument containing additional
28+
configuration options for the underlying [ConfigCat client](../../node#creating-the-configcat-client):
29+
30+
```ts
31+
import { Module } from '@nestjs/common';
32+
import { OpenFeatureModule } from '@openfeature/nestjs-sdk';
33+
import { ConfigCatProvider } from '@openfeature/config-cat-provider';
34+
import { createConsoleLogger, LogLevel, PollingMode } from 'configcat-js-ssr';
35+
import { FeatureFlagService } from './_services/feature-flag.service';
36+
37+
const configCatProvider = ConfigCatProvider.create('#YOUR-SDK-KEY#', PollingMode.AutoPoll, {
38+
// Specify options for the underlying ConfigCat client
39+
logger: createConsoleLogger(LogLevel.Info),
40+
setupHooks: (hooks) => hooks.on('clientReady', () => console.log('Client is ready!')),
41+
// ...
42+
});
43+
44+
@Module({
45+
imports: [
46+
OpenFeatureModule.forRoot({
47+
defaultProvider: configCatProvider,
48+
// Set the context for your evaluations
49+
contextFactory: (request) => ({ targetingKey: 'user-1' })
50+
}),
51+
],
52+
controllers: [/* ... */],
53+
providers: [FeatureFlagService],
54+
})
55+
export class AppModule {}
56+
```
57+
58+
### 3. Use your feature flag
59+
60+
To improve maintainability and testability, it's usually a good idea not to directly evaluate your feature flags, but to
61+
wrap them in a service:
62+
63+
```ts
64+
import { Injectable } from '@nestjs/common';
65+
import { OpenFeatureClient, Client } from '@openfeature/nestjs-sdk';
66+
67+
@Injectable()
68+
export class FeatureFlagService {
69+
constructor(
70+
@OpenFeatureClient() private readonly defaultClient: Client,
71+
) {
72+
}
73+
74+
public async isAwesomeFeatureEnabled() {
75+
return await this.defaultClient.getBooleanValue('isAwesomeFeatureEnabled', false);
76+
}
77+
}
78+
```
79+
80+
Then you can inject this service into your controllers and use it to evaluate feature flags:
81+
82+
```ts
83+
import { Controller, Get } from '@nestjs/common';
84+
import { FeatureFlagService } from './_services/feature-flag.service';
85+
86+
@Controller()
87+
export class AppController {
88+
constructor(
89+
private readonly featureFlagService: FeatureFlagService
90+
) {}
91+
92+
@Get()
93+
async welcome() {
94+
return await this.featureFlagService.isAwesomeFeatureEnabled()
95+
? 'Awesome feature is enabled!'
96+
: 'Awesome feature is disabled.';
97+
}
98+
}
99+
```
100+
101+
## Evaluation Context
102+
103+
An <a href="https://openfeature.dev/docs/reference/concepts/evaluation-context" target="_blank">evaluation context</a>
104+
in the OpenFeature specification is a container for arbitrary contextual data that can be used as a basis for feature
105+
flag evaluation.
106+
107+
You can find [here](./node.mdx#evaluation-context) how the ConfigCat provider translates these evaluation contexts to
108+
ConfigCat [User Objects](../../node/#user-object).
109+
110+
## Advanced features
111+
112+
Read the documentation of the [OpenFeature NestJS SDK](https://openfeature.dev/docs/reference/technologies/server/javascript/nestjs/)
113+
to learn more about the advanced capabilities of the SDK.
114+
115+
## Look under the hood
116+
117+
- <a href="https://github.com/open-feature/js-sdk-contrib/tree/main/libs/providers/config-cat" target="_blank">ConfigCat OpenFeature Provider's repository on GitHub</a>
118+
- <a href="https://www.npmjs.com/package/@openfeature/config-cat-provider" target="_blank">ConfigCat OpenFeature Provider in NPM</a>

‎website/docs/sdk-reference/openfeature/node.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ if (isAwesomeFeatureEnabled) {
5757

5858
On application shutdown, clean up the OpenFeature provider and the underlying ConfigCat client.
5959

60-
```cs
60+
```js
6161
await OpenFeature.clearProviders();
6262
```
6363

‎website/docs/sdk-reference/openfeature/overview.mdx

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,13 @@ OpenFeature providers are the abstraction between an OpenFeature SDK and an unde
1111
ConfigCat offers providers for the following platforms supported by OpenFeature SDKs:
1212

1313
- [.NET](./dotnet.mdx)
14+
- [Angular](./angular.mdx)
1415
- [Go](./go.mdx)
1516
- [Java](./java.mdx)
1617
- [JavaScript](./js.mdx)
18+
- [NestJS](./nestjs.mdx)
1719
- [Node.js](./node.mdx)
1820
- [PHP](./php.mdx)
1921
- [Python](./python.mdx)
22+
- [React](./react.mdx)
2023
- [Rust](./rust.mdx)

‎website/docs/sdk-reference/openfeature/react.mdx

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
id: react
3+
title: Using ConfigCat's OpenFeature Provider in React
4+
description: This is a step-by-step guide on how to use ConfigCat with the OpenFeature React SDK.
5+
---
6+
7+
import Tabs from '@theme/Tabs';
8+
import TabItem from '@theme/TabItem';
9+
10+
## Getting started
11+
12+
OpenFeature offers a [React SDK](https://github.com/open-feature/js-sdk/tree/main/packages/react) to streamline the use
13+
of OpenFeature in React applications. This SDK is built on top of the [OpenFeature JavaScript Web SDK](https://github.com/open-feature/js-sdk/blob/main/packages/web).
14+
15+
Since ConfigCat implements [a provider](./js.mdx) for the Web SDK, you can use ConfigCat with the OpenFeature React SDK,
16+
as explained below.
17+
18+
### 1. Install the React SDK and the ConfigCat provider
19+
20+
```bash
21+
npm i @openfeature/react-sdk @openfeature/config-cat-web-provider
22+
```
23+
24+
### 2. Initialize the React SDK
25+
26+
The `ConfigCatWebProvider.create()` function takes the SDK key and an optional `options` argument containing additional
27+
configuration options for the underlying [ConfigCat client](../../js#creating-the-configcat-client):
28+
29+
```jsx
30+
import { OpenFeature, OpenFeatureProvider } from '@openfeature/react-sdk';
31+
import { ConfigCatWebProvider } from '@openfeature/config-cat-web-provider';
32+
import { createConsoleLogger, LogLevel } from 'configcat-js-ssr';
33+
34+
const configCatProvider = ConfigCatWebProvider.create('#YOUR-SDK-KEY#', {
35+
// Specify options for the underlying ConfigCat client
36+
logger: createConsoleLogger(LogLevel.Info),
37+
setupHooks: (hooks) => hooks.on('clientReady', () => console.log('Client is ready!')),
38+
// ...
39+
});
40+
41+
// Set the initial context for your evaluations
42+
OpenFeature.setContext({
43+
targetingKey: 'user-1',
44+
admin: false
45+
});
46+
47+
// Instantiate and set our provider (be sure this only happens once)!
48+
// Note: there's no need to await its initialization, the React SDK handles re-rendering and suspense for you!
49+
OpenFeature.setProvider(configCatProvider);
50+
51+
// Enclose your content in the configured provider
52+
function App() {
53+
return (
54+
<OpenFeatureProvider>
55+
<Page />
56+
</OpenFeatureProvider>
57+
);
58+
}
59+
```
60+
61+
The `OpenFeatureProvider` is a [React context provider](https://react.dev/reference/react/createContext#provider) which
62+
represents a scope for feature flag evaluations within a React application. It binds an OpenFeature client to all
63+
evaluations within child components, and allows the use of evaluation hooks.
64+
65+
### 3. Use your feature flag
66+
67+
```jsx
68+
import { useFlag } from '@openfeature/react-sdk';
69+
70+
function Page() {
71+
// Use the "query-style" flag evaluation hook, specifying a flag-key and a default value.
72+
const { value: isAwesomeFeatureEnabled } = useFlag('isAwesomeFeatureEnabled', false);
73+
return (
74+
<div>
75+
{isAwesomeFeatureEnabled ? <p>Awesome feature is enabled!</p> : <p>Awesome feature is not enabled.</p>}
76+
</div>
77+
)
78+
}
79+
```
80+
81+
## Evaluation Context
82+
83+
An <a href="https://openfeature.dev/docs/reference/concepts/evaluation-context" target="_blank">evaluation context</a>
84+
in the OpenFeature specification is a container for arbitrary contextual data that can be used as a basis for feature
85+
flag evaluation.
86+
87+
You can find [here](./js.mdx#evaluation-context) how the ConfigCat provider translates these evaluation contexts to
88+
ConfigCat [User Objects](../../js/#user-object).
89+
90+
## Advanced features
91+
92+
Read the documentation of the [OpenFeature React SDK](https://openfeature.dev/docs/reference/technologies/client/web/react)
93+
to learn more about the advanced capabilities of the SDK.
94+
95+
## Look under the hood
96+
97+
- <a href="https://github.com/open-feature/js-sdk-contrib/tree/main/libs/providers/config-cat-web" target="_blank">ConfigCat OpenFeature Provider's repository on GitHub</a>
98+
- <a href="https://www.npmjs.com/package/@openfeature/config-cat-web-provider" target="_blank">ConfigCat OpenFeature Provider in NPM</a>

0 commit comments

Comments
 (0)