From 247f751fea274a29668aeeb2b1fa2e98f6bf759f Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 25 Jan 2023 14:36:50 +0100 Subject: [PATCH] docs: generate client-side SDK docs from readme (#2949) ## 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) --- .../how-to/how-to-capture-impression-data.mdx | 2 +- .../how-to/how-to-run-the-unleash-proxy.mdx | 2 +- .../how-to/how-to-use-custom-strategies.md | 2 +- .../reference/custom-activation-strategies.md | 2 +- website/docs/reference/sdks/android-proxy.md | 135 ------------ website/docs/reference/sdks/flutter.md | 75 ------- website/docs/reference/sdks/index.md | 24 +-- website/docs/reference/sdks/ios-proxy.md | 132 ------------ .../docs/reference/sdks/javascript-browser.md | 79 ------- website/docs/reference/sdks/react.md | 118 ----------- website/docs/reference/sdks/svelte.md | 198 ------------------ website/docs/reference/sdks/vue.md | 179 ---------------- website/docs/reference/unleash-proxy.md | 14 +- website/docs/tutorials/quickstart.md | 4 +- website/docusaurus.config.js | 1 + website/readme-fns.js | 91 ++++++-- website/sidebars.js | 11 +- 17 files changed, 102 insertions(+), 967 deletions(-) delete mode 100644 website/docs/reference/sdks/android-proxy.md delete mode 100644 website/docs/reference/sdks/flutter.md delete mode 100644 website/docs/reference/sdks/ios-proxy.md delete mode 100644 website/docs/reference/sdks/javascript-browser.md delete mode 100644 website/docs/reference/sdks/react.md delete mode 100644 website/docs/reference/sdks/svelte.md delete mode 100644 website/docs/reference/sdks/vue.md diff --git a/website/docs/how-to/how-to-capture-impression-data.mdx b/website/docs/how-to/how-to-capture-impression-data.mdx index 577ecd9c2c..db47446143 100644 --- a/website/docs/how-to/how-to-capture-impression-data.mdx +++ b/website/docs/how-to/how-to-capture-impression-data.mdx @@ -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 **``**. - **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. diff --git a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx index a00599edf7..3f922701bf 100644 --- a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx +++ b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx @@ -10,7 +10,7 @@ Placeholders in the code samples below are delimited by angle brackets (i.e. `

- io.getunleash - unleash-android-proxy-sdk - Latest version here - -``` - -### Step 2: Enable internet - -> NB - Your app will need internet permission in order to reach the proxy. So in your manifest add - -```xml - -``` - -### 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) diff --git a/website/docs/reference/sdks/flutter.md b/website/docs/reference/sdks/flutter.md deleted file mode 100644 index 56b7be8917..0000000000 --- a/website/docs/reference/sdks/flutter.md +++ /dev/null @@ -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 (`/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 -}); -``` diff --git a/website/docs/reference/sdks/index.md b/website/docs/reference/sdks/index.md index cdbf3fad4b..26af2559dd 100644 --- a/website/docs/reference/sdks/index.md +++ b/website/docs/reference/sdks/index.md @@ -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. -- [Android SDK](android-proxy.md) -- [Flutter Proxy SDK](flutter.md) -- [iOS Proxy SDK](ios-proxy.md) -- [Javascript SDK](javascript-browser.md) -- [React Proxy SDK](react.md) -- [Svelte Proxy SDK](svelte.md) -- [Vue Proxy SDK](vue.md) +- [Android SDK](/docs/generated/sdks/client-side/android-proxy.md) +- [Flutter Proxy SDK](/docs/generated/sdks/client-side/flutter.md) +- [iOS Proxy SDK](/docs/generated/sdks/client-side/ios-proxy.md) +- [Javascript SDK](/docs/generated/sdks/client-side/javascript-browser.md) +- [React Proxy SDK](/docs/generated/sdks/client-side/react.md) +- [Svelte Proxy SDK](/docs/generated/sdks/client-side/svelte.md) +- [Vue Proxy SDK](/docs/generated/sdks/client-side/vue.md) ### 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: -- [Android SDK](android-proxy.md) -- [Javascript SDK](javascript-browser.md) -- [React Proxy SDK](react.md) -- [Svelte Proxy SDK](svelte.md) -- [Vue Proxy SDK](vue.md) +- [Android SDK](/docs/generated/sdks/client-side/android-proxy.md) +- [Javascript SDK](/docs/generated/sdks/client-side/javascript-browser.md) +- [React Proxy SDK](/docs/generated/sdks/client-side/react.md) +- [Svelte Proxy SDK](/docs/generated/sdks/client-side/svelte.md) +- [Vue Proxy SDK](/docs/generated/sdks/client-side/vue.md) diff --git a/website/docs/reference/sdks/ios-proxy.md b/website/docs/reference/sdks/ios-proxy.md deleted file mode 100644 index 826910a304..0000000000 --- a/website/docs/reference/sdks/ios-proxy.md +++ /dev/null @@ -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. diff --git a/website/docs/reference/sdks/javascript-browser.md b/website/docs/reference/sdks/javascript-browser.md deleted file mode 100644 index 469ca9b1d0..0000000000 --- a/website/docs/reference/sdks/javascript-browser.md +++ /dev/null @@ -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 (`/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 -}); -``` diff --git a/website/docs/reference/sdks/react.md b/website/docs/reference/sdks/react.md deleted file mode 100644 index daf5d83fad..0000000000 --- a/website/docs/reference/sdks/react.md +++ /dev/null @@ -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 (`/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( - - - - - , - 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 ; - } - return ; -}; - -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 ; - } else if (variant.enabled && variant.name === 'AnotherComponent') { - return ; - } - return ; -}; - -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 }); - }, []); -}; -``` diff --git a/website/docs/reference/sdks/svelte.md b/website/docs/reference/sdks/svelte.md deleted file mode 100644 index 299016099c..0000000000 --- a/website/docs/reference/sdks/svelte.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -title: Svelte 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 [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 - - - - - -``` - -Alternatively, you can pass your own client in to the FlagProvider: - -```jsx - - - - - -``` - -## 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 - - - -``` - -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 - - - - - -``` - -## Usage - -### Check feature toggle status - -To check if a feature is enabled: - -```jsx - - -{#if $enabled} - -{:else} - -{/if} -``` - -### Check variants - -To check variants: - -```jsx - - -{#if $variant.enabled && $variant.name === 'SomeComponent'} - -{:else if $variant.enabled && $variant.name === 'AnotherComponent'} - -{:else} - -{/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 - - -{#if !$flagsReady} - -{:else} - -{/if} -``` - -### Updating context - -Follow the following steps in order to update the unleash context: - -```jsx - -``` diff --git a/website/docs/reference/sdks/vue.md b/website/docs/reference/sdks/vue.md deleted file mode 100644 index 67b655a0c0..0000000000 --- a/website/docs/reference/sdks/vue.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Vue 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 [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' -} - - -``` - -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) - - -``` - -## 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 - -``` - -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() -}) - - -``` - -## Usage - -### Check feature toggle status - -To check if a feature is enabled: - -```jsx - - - -``` - -### Check variants - -To check variants: - -```jsx - - - -``` - -### 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() - - - -``` - -### 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() -}) -``` diff --git a/website/docs/reference/unleash-proxy.md b/website/docs/reference/unleash-proxy.md index c4ad541a7a..5c8b63cee7 100644 --- a/website/docs/reference/unleash-proxy.md +++ b/website/docs/reference/unleash-proxy.md @@ -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: @@ -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. -- [Android Proxy SDK](sdks/android-proxy.md) -- [iOS Proxy SDK](sdks/ios-proxy.md) -- [Javascript Proxy SDK](sdks/javascript-browser.md) -- [React Proxy SDK](sdks/react.md) -- [Svelte Proxy SDK](sdks/svelte.md) -- [Vue Proxy SDK](sdks/vue.md) +- [Android Proxy SDK](/docs/generated/sdks/client-side/android-proxy.md) +- [iOS Proxy SDK](/docs/generated/sdks/client-side/ios-proxy.md) +- [Javascript Proxy SDK](/docs/generated/sdks/client-side/javascript-browser.md) +- [React Proxy SDK](/docs/generated/sdks/client-side/react.md) +- [Svelte Proxy SDK](/docs/generated/sdks/client-side/svelte.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. diff --git a/website/docs/tutorials/quickstart.md b/website/docs/tutorials/quickstart.md index d60d606f06..c56087cf92 100644 --- a/website/docs/tutorials/quickstart.md +++ b/website/docs/tutorials/quickstart.md @@ -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). -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 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. -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 import { UnleashClient } from 'unleash-proxy-client'; diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 62b7454176..5981b518a8 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -88,6 +88,7 @@ module.exports = { prism: { additionalLanguages: [ 'csharp', + 'dart', 'http', 'java', 'kotlin', diff --git a/website/readme-fns.js b/website/readme-fns.js index 5f6264ca77..0968a7ae01 100644 --- a/website/readme-fns.js +++ b/website/readme-fns.js @@ -14,8 +14,10 @@ // // type ReadmeData = Readme & { repoUrl: string }; -// all SDK repos and what they map to for the sidebar. -const sdksUnmapped = { +const CLIENT_SIDE_SDK = "client-side" +const SERVER_SIDE_SDK = "server-side" + +const serverSideSdks = { 'unleash-client-go': { sidebarName: 'Go', branch: 'v3', @@ -42,24 +44,62 @@ const sdksUnmapped = { sidebarName: '.NET', slugName: 'dotnet', }, - - // 'unleash-android-proxy-sdk': { - // sidebarName: 'Android', - // slugName: 'android-proxy', - // }, }; -const SDKS = Object.fromEntries( - Object.entries(sdksUnmapped).map(([repoName, repoData]) => { - const repoUrl = `https://github.com/Unleash/${repoName}`; - const slugName = ( - repoData.slugName ?? repoData.sidebarName - ).toLowerCase(); - const branch = repoData.branch ?? 'main'; +const clientSideSdks = { + 'unleash-android-proxy-sdk': { + sidebarName: 'Android', + slugName: 'android-proxy', + }, + unleash_proxy_client_flutter: { + 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) { const repoName = filename.split('/')[0]; @@ -116,8 +156,21 @@ const modifyContent = (filename, content) => { 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:///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 { - filename: `server-side/${sdk.slugName}.md`, + filename: `${sdk.type}/${sdk.slugName}.md`, content: `--- title: ${sdk.sidebarName} SDK slug: /reference/sdks/${sdk.slugName} @@ -130,7 +183,7 @@ This document was generated from the README in the [${ ::: :::tip Connecting to Unleash -To connect to Unleash, you'll need your Unleash API url (e.g. \`https:///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 } })} diff --git a/website/sidebars.js b/website/sidebars.js index 4a4bd2f871..5b475d6c99 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -242,13 +242,10 @@ module.exports = { type: 'category', label: 'Client-side SDKs', items: [ - 'reference/sdks/android-proxy', - 'reference/sdks/flutter', - 'reference/sdks/ios-proxy', - 'reference/sdks/javascript-browser', - 'reference/sdks/react', - 'reference/sdks/svelte', - 'reference/sdks/vue', + { + type: 'autogenerated', + dirName: 'generated/sdks/client-side', + }, ], }, {