Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2024-12-22 19:07:54 +01:00
Code Issues Projects Releases Wiki Activity

docs: generate client-side SDK docs from readme (#2949)

Browse Source 
## What

Delete static client-side SDK docs in favor of generating them at
build time.

- Add a separate list of `clientSideSdks` to `readme-fns`.
- Use sdk type to determine which generation directory it goes into
- Replace manual sidebar category with autogenerated one

## Why

This does the same for client-side SDKs as was done for server-side
SDKs in https://github.com/Unleash/unleash/pull/2858

(Supersedes #2859)
This commit is contained in:
Thomas Heartman 2023-01-25 14:36:50 +01:00 committed by GitHub
parent 96d4d355b1
commit 247f751fea
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 102 additions and 967 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
website/docs/how-to/how-to-capture-impression-data.mdx
View File

@ -23,7 +23,7 @@ We will assume that you have the necessary details for your third-party service:
- **where to send the data to**. We'll refer to this in the code samples below as **`<sink-url>`**. - **where to send the data to**. We'll refer to this in the code samples below as **`<sink-url>`**.
- **what format the data needs to be in**. This will determine how you transform the event data before you send it. - **what format the data needs to be in**. This will determine how you transform the event data before you send it.
In addition, you'll need to have a toggle to record impression data for and an [Unleash client SDK](../reference/sdks/index.md) that supports impression data. This guide will use the [JavaScript proxy SDK](../reference/sdks/javascript-browser.md). In addition, you'll need to have a toggle to record impression data for and an [Unleash client SDK](../reference/sdks/index.md) that supports impression data. This guide will use the [JavaScript proxy SDK](/docs/generated/sdks/client-side/javascript-browser.md).
When you have those things sorted, follow the below steps. When you have those things sorted, follow the below steps.

2
website/docs/how-to/how-to-run-the-unleash-proxy.mdx
View File

@ -10,7 +10,7 @@ Placeholders in the code samples below are delimited by angle brackets (i.e. `<p
::: :::
The [Unleash Proxy](../reference/unleash-proxy.md) provides a way for you to consume feature toggles in [front-end clients](../reference/sdks/index.md#front-end-sdks), such as the [JavaScript Proxy client](../reference/sdks/javascript-browser.md) and [React Proxy client](../reference/sdks/react.md). The [Unleash Proxy](../reference/unleash-proxy.md) provides a way for you to consume feature toggles in [front-end clients](../reference/sdks/index.md#front-end-sdks), such as the [JavaScript Proxy client](/docs/generated/sdks/client-side/javascript-browser.md) and [React Proxy client](/docs/generated/sdks/client-side/react.md).
Depending on your setup, the Proxy is most easily run in one of two ways, depending on your situation: Depending on your setup, the Proxy is most easily run in one of two ways, depending on your situation:

2
website/docs/how-to/how-to-use-custom-strategies.md
View File

@ -27,7 +27,7 @@ In this example we want to define an activation strategy offers a scheduled rele
The steps to implement a custom strategy for your client depend on the kind of client SDK you're using: The steps to implement a custom strategy for your client depend on the kind of client SDK you're using:
- if you're using a server-side client SDK, follow the steps in [option A](#step-3-a 'Step 3 option A: implement the strategy for a server-side client SDK'). - if you're using a server-side client SDK, follow the steps in [option A](#step-3-a 'Step 3 option A: implement the strategy for a server-side client SDK').
- if you're using a front-end client SDK ([Android](../reference/sdks/android-proxy.md), [JavaScript](../reference/sdks/javascript-browser.md), [React](../reference/sdks/react.md), [iOS](../reference/sdks/ios-proxy.md)), follow the steps in [option B](#step-3-b 'Step 3 option B: implementing the strategy for a front-end client SDK') - if you're using a front-end client SDK ([Android](/docs/generated/sdks/client-side/android-proxy.md), [JavaScript](/docs/generated/sdks/client-side/javascript-browser.md), [React](/docs/generated/sdks/client-side/react.md), [iOS](/docs/generated/sdks/client-side/ios-proxy.md)), follow the steps in [option B](#step-3-b 'Step 3 option B: implementing the strategy for a front-end client SDK')
### Option A: Implement the strategy for a server-side client SDK {#step-3-a} ### Option A: Implement the strategy for a server-side client SDK {#step-3-a}

2
website/docs/reference/custom-activation-strategies.md
View File

@ -62,6 +62,6 @@ If you have not implemented the strategy in your client SDK, the check will alwa
While custom strategies are _defined_ on the Unleash server, they must be _implemented_ on the client. All official Unleash client SDKs provide a way for you to implement custom strategies. You should refer to the individual SDK's documentation for specifics, but for an example, you can have a look at the [_Node.js client implementation_ section in the _how to use custom strategies_ guide](../how-to/how-to-use-custom-strategies.md#step-3-a). While custom strategies are _defined_ on the Unleash server, they must be _implemented_ on the client. All official Unleash client SDKs provide a way for you to implement custom strategies. You should refer to the individual SDK's documentation for specifics, but for an example, you can have a look at the [_Node.js client implementation_ section in the _how to use custom strategies_ guide](../how-to/how-to-use-custom-strategies.md#step-3-a).
The exact method for implementing custom strategies will vary between SDKs, but the server SDKs follow the same patterns. For front-end client SDKs ([Android](../reference/sdks/android-proxy.md), [JavaScript](../reference/sdks/javascript-browser.md), [React](../reference/sdks/react.md), [iOS](../reference/sdks/ios-proxy.md), [Flutter](../reference/sdks/flutter.md)), the custom activation strategy must be implemented in the [Unleash Proxy](../reference/unleash-proxy.md). The exact method for implementing custom strategies will vary between SDKs, but the server SDKs follow the same patterns. For front-end client SDKs ([Android](/docs/generated/sdks/client-side/android-proxy.md), [JavaScript](/docs/generated/sdks/client-side/javascript-browser.md), [React](/docs/generated/sdks/client-side/react.md), [iOS](/docs/generated/sdks/client-side/ios-proxy.md), [Flutter](/docs/generated/sdks/client-side/flutter.md)), the custom activation strategy must be implemented in the [Unleash Proxy](../reference/unleash-proxy.md).
When implementing a strategy in your client, you will get access to the strategy's parameters and the Unleash Context. Again, refer to your specific SDK's documentation for more details. When implementing a strategy in your client, you will get access to the strategy's parameters and the Unleash Context. Again, refer to your specific SDK's documentation for more details.

135
website/docs/reference/sdks/android-proxy.md
View File

@ -1,135 +0,0 @@
---
title: Android Proxy SDK
---
In this guide we'll explain how to use feature toggles in an Android application using Unleash's [Android Proxy SDK](https://github.com/Unleash/unleash-android-proxy-sdk) and the [Unleash Proxy](https://github.com/Unleash/unleash-proxy).
:::note
The Android proxy SDK requires the Unleash Proxy or _Unleash v4.16 or later_. Refer to the [Unleash front-end API documentation](../front-end-api.md) guide for simple setup. For large-scale, deployments refer to the [proxy documentation](../unleash-proxy.md) for how to set it up and [how to configure the proxy secrets](../unleash-proxy.md#configuration-variables).
:::
## How to use the Android Proxy SDK
### Step 1: Install the proxy SDK
First we must add unleash-android-proxy-sdk as a dependency to our project.
In gradle
```kotlin
implementation("io.getunleash:unleash-android-proxy-sdk:LATEST_VERSION")
```
In maven
```xml
<dependency>
<groupId>io.getunleash</groupId>
<artifactId>unleash-android-proxy-sdk</artifactId>
<version>Latest version here</version>
</dependency>
```
### Step 2: Enable internet
> NB - Your app will need internet permission in order to reach the proxy. So in your manifest add
```xml
<uses-permission android:name="android.permission.INTERNET" />
```
### Step 3: Configure Context
Since the proxy works by evaluating all feature toggles server side and returning the evaluated toggles back to the client, we'll need to configure the context to send to the proxy for evaluation.
```kotlin
import io.getunleash.UnleashContext
val myAppContext = UnleashContext.newBuilder()
.appName("Your AppName")
.userId("However you resolve your userid")
.sessionId("However you resolve your session id")
.build()
```
### Step 4: Configure the Client
To create a client, use the `UnleashConfig.newBuilder` method. When building a configuration, you'll need to provide it with:
- `proxyUrl`: the URL your proxy is available at
- `clientKey`: the [proxy client key](../unleash-proxy.md#configuration-variables) you wish to use (this method was known as `clientSecret` prior to version 0.4.0)
- `pollMode`: how you want to load the toggle status
As of v0.1 the SDK supports an automatic polling with an adjustable poll period or loading the state from disk. Most users will probably want to use the polling client, but it's nice to know that you can instantiate your client without actually needing Internet if you choose loading from File
#### Step 4a: Configure client polling proxy
Configuring a client with a 60 seconds poll interval
```kotlin
import io.getunleash.UnleashConfig
import io.getunleash.polling.PollingModes
val unleashConfig = UnleashConfig.newBuilder()
.proxyUrl("URL to your proxy installation")
.clientKey("yourProxySecret")
.pollMode(PollingModes.autoPoll(Duration.ofSeconds(60)) {
// This lambda will be called every time polling the server updates the toggle state
featuresUpdated()
})
.build()
```
#### Step 4b: Configure client loading toggles from a file
If you need to have a known state for your UnleashClient, you can perform a query against the proxy using your HTTP client of choice and save the output as a json file. Then you can tell Unleash to use this file to setup toggle states.
```kotlin
import io.getunleash.UnleashConfig
import io.getunleash.polling.PollingModes
val toggles = File("/tmp/proxyresponse.json")
val pollingMode = PollingModes.fileMode(toggles)
val unleashConfig = UnleashConfig.newBuilder()
.proxyUrl("Doesn't matter since we don't use it when sent a file")
.clientKey("Doesn't matter since we don't use it when sent a file")
.pollMode(pollingMode)
.build()
```
### Step 5: Instantiate the client
Having created your `UnleashContext` and your `UnleashConfig` you can now instantiate your client. Make sure you only do this once, and pass the instantiated client to classes/functions that need it.
```kotlin
import io.getunleash.UnleashClient
val unleashClient = UnleashClient(config = unleashConfig, context = myAppContext)
```
### Step 6: Use the feature toggle
Now that we have initialized the proxy SDK we can start using feature toggles defined in Unleash in our application. To achieve this we have the “isEnabled” method available, which will allow us to check the value of a feature toggle. This method will return true or false based on whether the feature should be enabled or disabled for the current state.
```kotlin
if (unleashClient.isEnabled("AwesomeFeature")) {
//do some magic
} else {
//do old boring stuff
}
```
## Updates
When using the AutoPoll mode you are able to pass in a listener which will get notified everytime our toggles changes, allowing you to recheck your toggles. For an example, see our [android-sample-app](https://github.com/Unleash/unleash-android-proxy-sdk/blob/main/samples/android/app/src/main/java/com/example/unleash/MainActivity.kt)
## KDoc
KDoc for the api is available at [https://docs.getunleash.io/unleash-android-proxy-sdk](https://docs.getunleash.io/unleash-android-proxy-sdk)
## Github
Readme for the client and source code is available at [https://github.com/Unleash/unleash-android-proxy-sdk](https://github.com/Unleash/unleash-android-proxy-sdk)

75
website/docs/reference/sdks/flutter.md
View File

@ -1,75 +0,0 @@
---
title: Flutter Proxy SDK
---
This guide shows you how to use feature toggles in a Flutter app with the [Unleash Proxy](../unleash-proxy.md) and the [Unleash front-end API](../front-end-api.md). You can also check out the source code for the [Flutter Proxy SDK](https://github.com/unleash/unleash_proxy_client_flutter) on GitHub for more details around the SDK.
## Introduction {#introduction}
The Flutter proxy client is a tiny Unleash client written in Dart. This client stores toggles relevant for the current user with [shared preferences library](https://pub.dev/packages/shared_preferences) and synchronizes with Unleash (the proxy _or_ the Unleash front-end API) in the background. Because toggles are stored in the user's device, the client can use them to bootstrap itself the next time the user visits the same web page.
## How to use the Flutter Proxy SDK
## Step 1: Install
```
flutter pub add unleash_proxy_client_flutter
```
## Step 2: Initialize the SDK
```dart
import 'package:unleash_proxy_client_flutter/unleash_proxy_client_flutter.dart';
final unleash = UnleashClient(
url: Uri.parse('https://app.unleash-hosted.com/demo/api/proxy'),
clientKey: 'proxy-123',
appName: 'my-app');
// Use `updateContext` to set Unleash context fields.
unleash.updateContext(UnleashContext(userId: '1233'));
// Start the background polling
unleash.start();
```
### Option A: Connecting to the Unleash proxy
:::tip Prerequisites
To connect to an Unleash proxy, you need to have an instance of the proxy running.
:::
Add the proxy's URL and a [proxy client key](../api-tokens-and-client-keys.mdx#proxy-client-keys). The [_configuration_ section of the Unleash proxy docs](../unleash-proxy.md#configuration-variables) contains more info on how to configure client keys for your proxy.
### Option B: Connecting directly to Unleash
Use the url to your Unleash instance's front-end API (`<unleash-url>/api/frontend`) as the `url` parameter. For the `clientKey` parameter, use a `FRONTEND` token generated from your Unleash instance. Refer to the [_how to create API tokens_](/how-to/how-to-create-api-tokens) guide for the necessary steps.
### Step 3: Check if feature toggle is enabled
```dart
unleash.isEnabled('proxy.demo');
```
...or get toggle variant:
```dart
final variant = unleash.getVariant('proxy.demo');
if(variant.name == 'blue') {
// something with variant blue...
}
```
## Listen for updates via the EventEmitter
The client is also an event emitter. This means that your code can subscribe to updates from the client. This is a neat way to update your app when toggle state updates.
```dart
unleash.on('update', (_) {
final myToggle = unleash.isEnabled('proxy.demo');
//do something useful
});
```

24
website/docs/reference/sdks/index.md
View File

@ -26,13 +26,13 @@ Server-side clients run on your server and communicate directly with your Unleas
Client-side SDKs can connect to the [Unleash Proxy](../unleash-proxy.md) or to the [Unleash front-end API](../front-end-api.md), but _not_ to the regular Unleash client API. Client-side SDKs can connect to the [Unleash Proxy](../unleash-proxy.md) or to the [Unleash front-end API](../front-end-api.md), but _not_ to the regular Unleash client API.
- [Android SDK](android-proxy.md) - [Android SDK](/docs/generated/sdks/client-side/android-proxy.md)
- [Flutter Proxy SDK](flutter.md) - [Flutter Proxy SDK](/docs/generated/sdks/client-side/flutter.md)
- [iOS Proxy SDK](ios-proxy.md) - [iOS Proxy SDK](/docs/generated/sdks/client-side/ios-proxy.md)
- [Javascript SDK](javascript-browser.md) - [Javascript SDK](/docs/generated/sdks/client-side/javascript-browser.md)
- [React Proxy SDK](react.md) - [React Proxy SDK](/docs/generated/sdks/client-side/react.md)
- [Svelte Proxy SDK](svelte.md) - [Svelte Proxy SDK](/docs/generated/sdks/client-side/svelte.md)
- [Vue Proxy SDK](vue.md) - [Vue Proxy SDK](/docs/generated/sdks/client-side/vue.md)
### Server-side SDK compatibility table ### Server-side SDK compatibility table
@ -142,8 +142,8 @@ By default, all SDKs reach out to the Unleash Server at startup to fetch their t
Bootstrapping is also supported by the following front-end client SDKs: Bootstrapping is also supported by the following front-end client SDKs:
- [Android SDK](android-proxy.md) - [Android SDK](/docs/generated/sdks/client-side/android-proxy.md)
- [Javascript SDK](javascript-browser.md) - [Javascript SDK](/docs/generated/sdks/client-side/javascript-browser.md)
- [React Proxy SDK](react.md) - [React Proxy SDK](/docs/generated/sdks/client-side/react.md)
- [Svelte Proxy SDK](svelte.md) - [Svelte Proxy SDK](/docs/generated/sdks/client-side/svelte.md)
- [Vue Proxy SDK](vue.md) - [Vue Proxy SDK](/docs/generated/sdks/client-side/vue.md)

132
website/docs/reference/sdks/ios-proxy.md
View File

@ -1,132 +0,0 @@
---
title: iOS Proxy SDK
---
In this guide we explain how to use feature toggles in Swift applications via the [Unleash Proxy](../unleash-proxy.md). You can also check out the [source code for the iOS Proxy SDK](https://github.com/Unleash/unleash-proxy-client-swift).
## Introduction {#introduction}
The unleash-proxy-client-swift makes it easy for native applications and other swift platforms to connect to the unleash proxy. The proxy will evaluate a feature toggle for a given [context](../../reference/unleash-context.md) and return a list of feature flags relevant for the provided context.
The unleash-proxy-client-swift will then cache these toggles in a map in memory and refresh the configuration at a configurable interval, making queries against the toggle configuration extremely fast.
## Requirements
- MacOS: 12.15
- iOS: 13
## Installation
Follow the following steps in order to install the unleash-proxy-client-swift:
1. In your Xcode project go to File -> Swift Packages -> Add Package Dependency
2. Supply the link to this repository
3. Set the appropriate package constraints (typically up to next major version)
4. Let Xcode find and install the necessary packages
Once you're done, you should see SwiftEventBus and UnleashProxyClientSwift listed as dependencies in the file explorer of your project.
## Usage
In order to get started you need to import and instantiate the unleash client:
```swift
import SwiftUI
// Import UnleashProxyClientSwift
import UnleashProxyClientSwift
// Setup Unleash in the context where it makes most sense
var unleash = UnleashProxyClientSwift.UnleashClient(
unleashUrl: "https://app.unleash-hosted.com/hosted/api/proxy",
clientKey: "PROXY_KEY",
refreshInterval: 15,
appName: "test",
environment: "dev")
unleash.start()
```
In the example above we import the `UnleashProxyClientSwift` and instantiate the client. You need to provide the following parameters:
- `unleashUrl` (`String`)
The full URL to your proxy instance.
- `clientKey` (`String`)
One of the configured [proxy keys / proxy secrets](../unleash-proxy.md#configuration-variables).
- `refreshInterval` (`Int`)
The polling interval in seconds.
- `appName` (`String`)
The application name; only used to identify your application.
- `environment` (`String`)
The application environment. This corresponds to the environment field in [the Unleash Context](../../reference/unleash-context.md). Note that this is separate from the newer [Environments feature](../../reference/environments.md).
Running `unleash.start()` will make the first request against the proxy and retrieve the feature toggle configuration, and set up the polling interval in the background.
NOTE: While waiting to boot up the configuration may not be available, which means that asking for a feature toggle may result in a false if the configuration has not loaded. In the event that you need to be certain that the configuration is loaded we emit an event you can subscribe to, once the configuration is loaded. See more in the Events section.
Once the configuration is loaded you can ask against the cache for a given feature toggle:
```swift
if unleash.isEnabled(name: "ios") {
// do something
} else {
// do something else
}
```
You can also set up [variants](https://docs.getunleash.io/docs/reference/feature-toggle-variants) and use them in a similar fashion:
```swift
var variant = unleash.getVariant(name: "ios")
if variant.enabled {
// do something
} else {
// do something else
}
```
### Update context
In order to update the context you can use the following method:
```swift
var context: [String: String] = [:]
context["userId"] = "c3b155b0-5ebe-4a20-8386-e0cab160051e"
unleash.updateContext(context: context)
```
This will stop and start the polling interval in order to renew polling with new context values.
## Events
The proxy client emits two different events you can subscribe to:
- "ready"
- "update"
Usage them in the following manner:
```swift
func handleReady() {
// do this when unleash is ready
}
unleash.subscribe(name: "ready", callback: handleReady)
func handleUpdate() {
// do this when unleash is updated
}
unleash.subscribe(name: "update", callback: handleUpdate)
```
The ready event is fired once the client has received it's first set of feature toggles and cached it in memory. Every subsequent event will be an update event that is triggered if there is a change in the feature toggle configuration.

79
website/docs/reference/sdks/javascript-browser.md
View File

@ -1,79 +0,0 @@
---
title: JavaScript Proxy SDK
---
This guide shows you how to use feature toggles in a single-page app with the [Unleash Proxy](../unleash-proxy.md) and the [Unleash front-end API](../front-end-api.md). You can also check out the source code for the [JavaScript Proxy SDK](https://github.com/unleash/unleash-proxy-client-js) on GitHub for more details around the SDK.
## Introduction {#introduction}
The JavaScript proxy client is a tiny Unleash client written in JavaScript without any external dependencies (except from browser APIs). This client stores toggles relevant for the current user in `localStorage` and synchronizes with Unleash (the proxy _or_ the Unleash front-end API) in the background. Because toggles are stored in the user's browser, the client can use them to bootstrap itself the next time the user visits the same web page.
> We are looking in to also [supporting react-native](https://github.com/Unleash/unleash/issues/785) with this SDK. Reach out if you want to help us validate the implementation.
## How to use the JavaScript Proxy SDK
## Step 1: Install
```shell npm2yarn
npm install unleash-proxy-client
```
## Step 2: Initialize the SDK
```js
import { UnleashClient } from 'unleash-proxy-client';
const unleash = new UnleashClient({
url: 'https://eu.unleash-hosted.com/hosted/proxy',
clientKey: 'your-client-key',
appName: 'my-webapp',
});
// Use `updateContext` to set Unleash context fields.
unleash.updateContext({ userId: '1233' });
// Start the background polling
unleash.start();
```
### Option A: Connecting to the Unleash proxy
:::tip Prerequisites
To connect to an Unleash proxy, you need to have an instance of the proxy running.
:::
Add the proxy's URL and a [proxy client key](../api-tokens-and-client-keys.mdx#proxy-client-keys). The [_configuration_ section of the Unleash proxy docs](../unleash-proxy.md#configuration-variables) contains more info on how to configure client keys for your proxy.
### Option B: Connecting directly to Unleash
Use the url to your Unleash instance's front-end API (`<unleash-url>/api/frontend`) as the `url` parameter. For the `clientKey` parameter, use a `FRONTEND` token generated from your Unleash instance. Refer to the [_how to create API tokens_](/how-to/how-to-create-api-tokens) guide for the necessary steps.
You might also need to set up cross-origin resource sharing (CORS) for your instance. Visit the [CORS section of the front-end API guide](../front-end-api.md#cors) for more information on setting up CORS.
### Step 3: Check if feature toggle is enabled
```js
unleash.isEnabled('proxy.demo');
```
...or get toggle variant:
```js
const variant = unleash.getVariant('proxy.demo');
if (variant.name === 'blue') {
// something with variant blue...
}
```
## Listen for updates via the EventEmitter
The client is also an event emitter. This means that your code can subscribe to updates from the client. This is a neat way to update a single page app when toggle state updates.
```js
unleash.on('update', () => {
const myToggle = unleash.isEnabled('proxy.demo');
//do something useful
});
```

118
website/docs/reference/sdks/react.md
View File

@ -1,118 +0,0 @@
---
title: React Proxy SDK
---
This library can be used with the [Unleash Proxy](https://github.com/Unleash/unleash-proxy) or with the [Unleash front-end API](../front-end-api.md). It is _not_ compatible with the regular Unleash client API.
For more detailed information, check out the [React Proxy SDK on GitHub](https://github.com/Unleash/proxy-client-react).
## Installation
Install the React proxy client and the [JavaScript proxy client](javascript-browser.md) packages:
```shell npm2yarn
npm install @unleash/proxy-client-react unleash-proxy-client
```
## Initialization
The snippet below shows you how to initialize the client. We recommend that you do this in your entry point file (typically index.js/ts) to ensure that you only have _one_ instance of it.
The configuration variables are:
- **`url`**
Your proxy's URL or the Unleash front-end API endpoint (`<unleash-url>/api/frontend`).
- **`clientKey`**
One of your proxy's [designated client keys (also known as proxy secrets)](../unleash-proxy.md#configuration-variables).
- **`refreshInterval`**
How often (in seconds) the client should poll the proxy for updates.
- **`appName`**
The name of your application. It's only used for identifying your application and can be whatever you want it to be.
- **`environment`**
The environment that your application runs in. This corresponds to the environment field in [the Unleash Context](../../reference/unleash-context.md). Note that this is separate from the newer [Environments feature](../../reference/environments.md).
```jsx
import { FlagProvider } from '@unleash/proxy-client-react';
const config = {
url: 'https://PROXY_HOSTNAME/api/proxy', // or https://UNLEASH_HOSTNAME/api/frontend
clientKey: 'PROXYKEY',
refreshInterval: 15,
appName: 'your-app-name',
environment: 'dev',
};
ReactDOM.render(
<React.StrictMode>
<FlagProvider config={config}>
<App />
</FlagProvider>
</React.StrictMode>,
document.getElementById('root'),
);
```
## How to check feature toggle states
To check if a feature is enabled:
```jsx
import { useFlag } from '@unleash/proxy-client-react';
const TestComponent = () => {
const enabled = useFlag('travel.landing');
if (enabled) {
return <SomeComponent />;
}
return <AnotherComponent />;
};
export default TestComponent;
```
To check variants:
```jsx
import { useVariant } from '@unleash/proxy-client-react';
const TestComponent = () => {
const variant = useVariant('travel.landing');
if (variant.enabled && variant.name === 'SomeComponent') {
return <SomeComponent />;
} else if (variant.enabled && variant.name === 'AnotherComponent') {
return <AnotherComponent />;
}
return <DefaultComponent />;
};
export default TestComponent;
```
## How to update the Unleash Context
Follow the following steps in order to update the unleash context:
```jsx
import { useUnleashContext, useFlag } from '@unleash/proxy-client-react';
const MyComponent = ({ userId }) => {
const variant = useFlag('my-toggle');
const updateContext = useUnleashContext();
useEffect(() => {
// context is updated with userId
updateContext({ userId });
}, []);
};
```

198
website/docs/reference/sdks/svelte.md
View File

@ -1,198 +0,0 @@
---
title: Svelte Proxy SDK
---
<div class="alert alert--info" role="alert">
<em>Svelte Proxy SDK is currently at version 0.0.2 and is experimental</em>.
</div>
<br/>
This library can be used with the [Unleash Proxy](https://github.com/Unleash/unleash-proxy) or with the [Unleash front-end API](../front-end-api.md). It is _not_ compatible with the regular Unleash client API.
For more detailed information, check out the [Svelte Proxy SDK on GitHub](https://github.com/Unleash/proxy-client-svelte).
## Installation
```shell npm2yarn
npm install @unleash/proxy-client-svelte
```
## Initialization
Import the provider like this in your entrypoint file (typically index.svelte):
```jsx
<script lang="ts">
let FlagProvider;
onMount(async () => {
const proxyClientSvelte = await import('@unleash/proxy-client-svelte');
({ FlagProvider } = proxyClientSvelte);
});
const config = {
url: 'https://HOSTNAME/proxy',
clientKey: 'PROXYKEY',
refreshInterval: 15,
appName: 'your-app-name',
environment: 'dev'
};
</script>
<svelte:component this={FlagProvider} {config}>
<App />
</svelte:component>
```
Alternatively, you can pass your own client in to the FlagProvider:
```jsx
<script lang="ts">
import { UnleashClient } from '@unleash/proxy-client-svelte';
let FlagProvider;
onMount(async () => {
const proxyClientSvelte = await import('@unleash/proxy-client-svelte');
({ FlagProvider } = proxyClientSvelte);
});
const config = {
url: 'https://HOSTNAME/proxy',
clientKey: 'PROXYKEY',
refreshInterval: 15,
appName: 'your-app-name',
environment: 'dev'
};
const client = new UnleashClient(config);
</script>
<svelte:component this={FlagProvider} unleashClient={client}>
<App />
</svelte:component>
```
## Deferring client start
By default, the Unleash client will start polling the Proxy for toggles immediately when the `FlagProvider` component renders. You can delay the polling by:
- setting the `startClient` prop to `false`
- passing a client instance to the `FlagProvider`
```jsx
<svelte:component
this={FlagProvider}
unleashClient={client}
startClient={false}
>
<App />
</svelte:component>
```
Deferring the client start gives you more fine-grained control over when to start fetching the feature toggle configuration. This could be handy in cases where you need to get some other context data from the server before fetching toggles, for instance.
To start the client, use the client's `start` method. The below snippet of pseudocode will defer polling until the end of the `asyncProcess` function.
```jsx
<script lang="ts">
const client = new UnleashClient({
/* ... */
});
onMount(() => {
const asyncProcess = async () => {
// do async work ...
client.start();
};
asyncProcess();
});
</script>
<svelte:component this={FlagProvider} unleashClient={client} startClient={false}>
<App />
</svelte:component>
```
## Usage
### Check feature toggle status
To check if a feature is enabled:
```jsx
<script lang="ts">
import { useFlag } from '@unleash/proxy-client-svelte';
const enabled = useFlag('travel.landing');
</script>
{#if $enabled}
<SomeComponent />
{:else}
<AnotherComponent />
{/if}
```
### Check variants
To check variants:
```jsx
<script lang="ts">
import { useVariant } from '@unleash/proxy-client-svelte';
const variant = useVariant('travel.landing');
</script>
{#if $variant.enabled && $variant.name === 'SomeComponent'}
<SomeComponent />
{:else if $variant.enabled && $variant.name === 'AnotherComponent'}
<AnotherComponent />
{:else}
<DefaultComponent />
{/if}
```
### Defer rendering until flags fetched
useFlagsStatus retrieves the ready state and error events. Follow the following steps in order to delay rendering until the flags have been fetched.
```jsx
<script lang="ts">
import { useFlagsStatus } from '@unleash/proxy-client-svelte';
const { flagsReady, flagsError } = useFlagsStatus();
</script>
{#if !$flagsReady}
<Loading />
{:else}
<MyComponent error={flagsError} />
{/if}
```
### Updating context
Follow the following steps in order to update the unleash context:
```jsx
<script lang="ts">
import { useUnleashContext, useFlag } from '@unleash/proxy-client-svelte';
export let userId: string = undefined;
const updateContext = useUnleashContext();
onMount(() => {
updateContext({ userId });
});
$: {
async function run() {
await updateContext({ userId });
console.log('new flags loaded for', userId);
}
run();
}
</script>
```

179
website/docs/reference/sdks/vue.md
View File

@ -1,179 +0,0 @@
---
title: Vue Proxy SDK
---
<div class="alert alert--info" role="alert">
<em>Vue Proxy SDK is currently at version 0.0.1 and is experimental</em>.
</div>
<br/>
This library can be used with the [Unleash Proxy](https://github.com/Unleash/unleash-proxy) or with the [Unleash front-end API](../front-end-api.md). It is _not_ compatible with the regular Unleash client API.
For more detailed information, check out the [Vue Proxy SDK on GitHub](https://github.com/Unleash/proxy-client-vue).
## Installation
```shell npm2yarn
npm install @unleash/proxy-client-vue
```
## Initialization
Import the provider like this in your entrypoint file (typically App.vue):
```jsx
import { FlagProvider } from '@unleash/proxy-client-vue'
const config = {
url: 'https://HOSTNAME/proxy',
clientKey: 'PROXYKEY',
refreshInterval: 15,
appName: 'your-app-name',
environment: 'dev'
}
<template>
<FlagProvider :config="config">
<App />
</FlagProvider>
</template>
```
Alternatively, you can pass your own client in to the FlagProvider:
```jsx
import { FlagProvider, UnleashClient } from '@unleash/proxy-client-vue'
const config = {
url: 'https://HOSTNAME/proxy',
clientKey: 'PROXYKEY',
refreshInterval: 15,
appName: 'your-app-name',
environment: 'dev'
}
const client = new UnleashClient(config)
<template>
<FlagProvider :unleash-client="client">
<App />
</FlagProvider>
</template>
```
## Deferring client start
By default, the Unleash client will start polling the Proxy for toggles immediately when the `FlagProvider` component renders. You can delay the polling by:
- setting the `startClient` prop to `false`
- passing a client instance to the `FlagProvider`
```jsx
<template>
<FlagProvider :unleash-client="client" :start-client="false">
<App />
</FlagProvider>
</template>
```
Deferring the client start gives you more fine-grained control over when to start fetching the feature toggle configuration. This could be handy in cases where you need to get some other context data from the server before fetching toggles, for instance.
To start the client, use the client's `start` method. The below snippet of pseudocode will defer polling until the end of the `asyncProcess` function.
```jsx
const client = new UnleashClient({
/* ... */
})
onMounted(() => {
const asyncProcess = async () => {
// do async work ...
client.start()
}
asyncProcess()
})
<template>
<FlagProvider :unleash-client="client" :start-client="false">
<App />
</FlagProvider>
</template>
```
## Usage
### Check feature toggle status
To check if a feature is enabled:
```jsx
<script setup>
import { useFlag } from '@unleash/proxy-client-vue'
const enabled = useFlag('travel.landing')
</script>
<template>
<SomeComponent v-if="enabled" />
<AnotherComponent v-else />
</template>
```
### Check variants
To check variants:
```jsx
<script setup>
import { useVariant } from '@unleash/proxy-client-vue'
const variant = useVariant('travel.landing')
</script>
<template>
<SomeComponent v-if="variant.enabled && variant.name === 'SomeComponent'" />
<AnotherComponent v-else-if="variant.enabled && variant.name === 'AnotherComponent" />
<DefaultComponent v-else />
</template>
```
### Defer rendering until flags fetched
useFlagsStatus retrieves the ready state and error events. Follow the following steps in order to delay rendering until the flags have been fetched.
```jsx
import { useFlagsStatus } from '@unleash/proxy-client-vue'
const { flagsReady, flagsError } = useFlagsStatus()
<Loading v-if="!flagsReady" />
<MyComponent v-else error={flagsError} />
```
### Updating context
Follow the following steps in order to update the unleash context:
```jsx
import { useUnleashContext, useFlag } from '@unleash/proxy-client-vue'
const props = defineProps<{
userId: string
}>()
const { userId } = toRefs(props)
const updateContext = useUnleashContext()
onMounted(() => {
updateContext({ userId })
})
watch(userId, () => {
async function run() {
await updateContext({ userId: userId.value })
console.log('new flags loaded for', userId.value)
}
run()
})
```

14
website/docs/reference/unleash-proxy.md
View File

@ -101,7 +101,7 @@ Custom activation strategies can **not** be used with the Unleash-hosted proxy a
::: :::
The Unleash Proxy can load [custom activation strategies](../reference/custom-activation-strategies.md) for front-end client SDKs ([Android](./sdks/android-proxy.md), [JavaScript](./sdks/javascript-browser.md), [React](./sdks/react.md), [iOS](./sdks/ios-proxy.md), [Flutter](./sdks/flutter.md)). For a step-by-step guide, refer to the [_how to use custom strategies_ guide](../how-to/how-to-use-custom-strategies.md#step-3-b). The Unleash Proxy can load [custom activation strategies](../reference/custom-activation-strategies.md) for front-end client SDKs ([Android](/docs/generated/sdks/client-side/android-proxy.md), [JavaScript](/docs/generated/sdks/client-side/javascript-browser.md), [React](/docs/generated/sdks/client-side/react.md), [iOS](/docs/generated/sdks/client-side/ios-proxy.md), [Flutter](/docs/generated/sdks/client-side/flutter.md)). For a step-by-step guide, refer to the [_how to use custom strategies_ guide](../how-to/how-to-use-custom-strategies.md#step-3-b).
To load custom strategies, use either of these two options: To load custom strategies, use either of these two options:
@ -271,11 +271,11 @@ The Unleash Proxy takes the heavy lifting of evaluating toggles and only returns
However in some settings you would like a bit more logic around it to make it as fast as possible, and keep up to date with changes. However in some settings you would like a bit more logic around it to make it as fast as possible, and keep up to date with changes.
- [Android Proxy SDK](sdks/android-proxy.md) - [Android Proxy SDK](/docs/generated/sdks/client-side/android-proxy.md)
- [iOS Proxy SDK](sdks/ios-proxy.md) - [iOS Proxy SDK](/docs/generated/sdks/client-side/ios-proxy.md)
- [Javascript Proxy SDK](sdks/javascript-browser.md) - [Javascript Proxy SDK](/docs/generated/sdks/client-side/javascript-browser.md)
- [React Proxy SDK](sdks/react.md) - [React Proxy SDK](/docs/generated/sdks/client-side/react.md)
- [Svelte Proxy SDK](sdks/svelte.md) - [Svelte Proxy SDK](/docs/generated/sdks/client-side/svelte.md)
- [Vue Proxy SDK](sdks/vue.md) - [Vue Proxy SDK](/docs/generated/sdks/client-side/vue.md)
The proxy is also ideal fit for serverless functions such as AWS Lambda. In that scenario the proxy can run on a small container near the serverless function, preferably in the same VPC, giving the lambda extremely fast access to feature flags, at a predictable cost. The proxy is also ideal fit for serverless functions such as AWS Lambda. In that scenario the proxy can run on a small container near the serverless function, preferably in the same VPC, giving the lambda extremely fast access to feature flags, at a predictable cost.

4
website/docs/tutorials/quickstart.md
View File

@ -34,7 +34,7 @@ If you don't have your own Unleash instance set up, you can use the Unleash demo
Now you can open your application code and connect through one of the [client-side SDKs](../reference/sdks#client-side-sdks). Now you can open your application code and connect through one of the [client-side SDKs](../reference/sdks#client-side-sdks).
The following example shows you how you could use the [JavaScript SDK](../generated/sdks/client-side/javascript-browser.mdx) to connect to the Unleash demo proxy: The following example shows you how you could use the [JavaScript SDK](../generated/sdks/client-side/javascript-browser.md) to connect to the Unleash demo proxy:
```javascript ```javascript
import { UnleashClient } from 'unleash-proxy-client'; import { UnleashClient } from 'unleash-proxy-client';
@ -322,7 +322,7 @@ The easiest way to connect a client-side SDK to your Unleash instance is to use
The section on [using the Unleash front-end API](../reference/front-end-api.md#using-the-unleash-front-end-api) has more details for how you configure these settings. The section on [using the Unleash front-end API](../reference/front-end-api.md#using-the-unleash-front-end-api) has more details for how you configure these settings.
As an example, here's how you would connect the [JavaScript SDK](../generated/sdks/client-side/javascript-browser.mdx) to a local Unleash instance available at `localhost:4242` As an example, here's how you would connect the [JavaScript SDK](../generated/sdks/client-side/javascript-browser.md) to a local Unleash instance available at `localhost:4242`
```javascript ```javascript
import { UnleashClient } from 'unleash-proxy-client'; import { UnleashClient } from 'unleash-proxy-client';

1
website/docusaurus.config.js
View File

@ -88,6 +88,7 @@ module.exports = {
prism: { prism: {
additionalLanguages: [ additionalLanguages: [
'csharp', 'csharp',
'dart',
'http', 'http',
'java', 'java',
'kotlin', 'kotlin',

91
website/readme-fns.js
View File

@ -14,8 +14,10 @@
// //
// type ReadmeData = Readme & { repoUrl: string }; // type ReadmeData = Readme & { repoUrl: string };
// all SDK repos and what they map to for the sidebar. const CLIENT_SIDE_SDK = "client-side"
const sdksUnmapped = { const SERVER_SIDE_SDK = "server-side"
const serverSideSdks = {
'unleash-client-go': { 'unleash-client-go': {
sidebarName: 'Go', sidebarName: 'Go',
branch: 'v3', branch: 'v3',
@ -42,24 +44,62 @@ const sdksUnmapped = {
sidebarName: '.NET', sidebarName: '.NET',
slugName: 'dotnet', slugName: 'dotnet',
}, },
// 'unleash-android-proxy-sdk': {
// sidebarName: 'Android',
// slugName: 'android-proxy',
// },
}; };
const SDKS = Object.fromEntries( const clientSideSdks = {
Object.entries(sdksUnmapped).map(([repoName, repoData]) => { 'unleash-android-proxy-sdk': {
const repoUrl = `https://github.com/Unleash/${repoName}`; sidebarName: 'Android',
const slugName = ( slugName: 'android-proxy',
repoData.slugName ?? repoData.sidebarName },
).toLowerCase(); unleash_proxy_client_flutter: {
const branch = repoData.branch ?? 'main'; sidebarName: 'Flutter',
},
'unleash-proxy-client-swift': {
sidebarName: 'iOS',
slugName: 'ios-proxy',
},
'unleash-proxy-client-js': {
sidebarName: 'JavaScript browser',
slugName: 'javascript-browser',
},
'proxy-client-react': {
sidebarName: 'React',
},
'proxy-client-svelte': {
sidebarName: 'Svelte',
},
'proxy-client-vue': {
sidebarName: 'Vue',
},
};
return [repoName, { ...repoData, repoUrl, slugName, branch }]; const allSdks = () => {
}), const enrich =
); (sdkType) =>
([repoName, repoData]) => {
const repoUrl = `https://github.com/Unleash/${repoName}`;
const slugName = (
repoData.slugName ?? repoData.sidebarName
).toLowerCase();
const branch = repoData.branch ?? 'main';
return [
repoName,
{ ...repoData, repoUrl, slugName, branch, type: sdkType },
];
};
const serverSide = Object.entries(serverSideSdks).map(
enrich(SERVER_SIDE_SDK),
);
const clientSide = Object.entries(clientSideSdks).map(
enrich(CLIENT_SIDE_SDK),
);
return Object.fromEntries(serverSide.concat(clientSide));
};
const SDKS = allSdks();
function getReadmeRepoData(filename) { function getReadmeRepoData(filename) {
const repoName = filename.split('/')[0]; const repoName = filename.split('/')[0];
@ -116,8 +156,21 @@ const modifyContent = (filename, content) => {
const generationTime = new Date(); const generationTime = new Date();
const getConnectionTip = (sdkType) => {
switch (sdkType) {
case CLIENT_SIDE_SDK: return `To connect this SDK to Unleash, you'll need to use either
- the [Unleash front-end API](/reference/front-end-api) (released in Unleash 4.16) ([how do I create an API token?](/how-to/how-to-create-api-tokens.mdx))
- the [Unleash proxy](/reference/unleash-proxy) ([how do I create client keys?](/reference/api-tokens-and-client-keys#proxy-client-keys))
This SDK **cannot** connect to the regular (server-side) \`client\` API.`
case SERVER_SIDE_SDK:
default: return `To connect to Unleash, you'll need your Unleash API url (e.g. \`https://<your-unleash>/api\`) and a [server-side API token](/reference/api-tokens-and-client-keys.mdx#client-tokens) ([how do I create an API token?](/how-to/how-to-create-api-tokens.mdx)).`
}
}
return { return {
filename: `server-side/${sdk.slugName}.md`, filename: `${sdk.type}/${sdk.slugName}.md`,
content: `--- content: `---
title: ${sdk.sidebarName} SDK title: ${sdk.sidebarName} SDK
slug: /reference/sdks/${sdk.slugName} slug: /reference/sdks/${sdk.slugName}
@ -130,7 +183,7 @@ This document was generated from the README in the [${
::: :::
:::tip Connecting to Unleash :::tip Connecting to Unleash
To connect to Unleash, you'll need your Unleash API url (e.g. \`https://<your-unleash>/api\`) and a [server-side API token](/reference/api-tokens-and-client-keys.mdx#client-tokens) ([how do I create an API token?](/how-to/how-to-create-api-tokens.mdx)). ${getConnectionTip(sdk.type)}
::: :::
${replaceLinks({ content, repo: { url: sdk.repoUrl, branch: sdk.branch } })} ${replaceLinks({ content, repo: { url: sdk.repoUrl, branch: sdk.branch } })}

11
website/sidebars.js
View File

@ -242,13 +242,10 @@ module.exports = {
type: 'category', type: 'category',
label: 'Client-side SDKs', label: 'Client-side SDKs',
items: [ items: [
'reference/sdks/android-proxy', {
'reference/sdks/flutter', type: 'autogenerated',
'reference/sdks/ios-proxy', dirName: 'generated/sdks/client-side',
'reference/sdks/javascript-browser', },
'reference/sdks/react',
'reference/sdks/svelte',
'reference/sdks/vue',
], ],
}, },
{ {