415e1b0596
## What The main purpose of this PR is to 1. Delete the proxy docs in this repo and replace them with the proxy's GitHub readme. 2. Add the docs for Unleash Edge. ### Detailed change description This PR contains a lot of small changes in a large number of files. To make it easier to get an overview, here's a detailed description of what happens where: #### In the `website/docs`directory Except for the deletion of the proxy doc, all changes in this directory are rewriting internal links, so that they point to the newly generated document instead. #### `package.json` and `yarn.lock` When including the documentation for Edge, we also want to render the mermaid diagrams it uses. Docusaurus supports this via a plugin. All changes in these files are related to installing that plugin. #### `docusaurus.config.js` There's two types of changes in this file: 1. Mermaid-related changes: we ask docusaurus to render mermaid in markdown files and add the plugin 2. Document generation. There's some rewrites to the sdk doc generation plus an entirely new section that generates docs for Edge and the proxy #### `sidebars.js` Two things: 1. Add the edge docs 2. Move both the Edge and the proxy docs up a level, so that they're directly under "reference docs" instead of nested inside "unleash concepts". #### In the `website/remote-content` directory These are the remote content files. Previously, all of this lived only in a `readme-fns.js` file, but with the introduction of Edge and proxy docs, this has been moved into its own directory and refactored into three files (`shared`, `sdks`, `edge-proxy`). #### `custom.css` Style updates to center mermaid diagrams and provide more space around them. #### In `static/img` The image files that were included in the proxy doc and that have been deleted. ## Why For two reasons: 1. Reduce duplication for the proxy. Have one source of truth. 2. Add docs for edge. ## Discussion points and review wishes This is a big PR, and I don't expect anyone to do a line-by-line review of it, nor do I think that is particularly useful. Instead, I'd like to ask reviewers to: 1. Visit the [documentation preview](https://unleash-docs-git-docs-source-proxy-gh-unleash-team.vercel.app/reference/unleash-proxy) and have a look at both the proxy docs and the Edge docs. Potentially have a look at the SDK docs too to verify that everything still works. 2. Consider whether they think moving the proxy and edge docs up a level (in the sidebar) makes sense. 3. Let me know what slug they'd prefer for the Edge docs. I've gone with `unleash-edge` for now (so that it's `docs.getunleash.io/reference/unleash-edge`), but we could potentially also just use `edge`. WDYT? 4. Read through the detailed changes section. 5. Let me know if they have any other concerns or questions. ## Screenies The new proxy doc:  The new edge doc: 
3.9 KiB
| title |
|---|
| Front-end API access |
:::info Availability
The Unleash front-end API was released in Unleash 4.18. You can read more in the Unleash 4.18 release blog post.
:::
The Unleash front-end API offers a simplified workflow for connecting a client-side (front-end) applications to Unleash. It provides the exact same API as the Unleash proxy. The front-end API is a quick and easy way to add Unleash to single-page applications and mobile apps.
Compared to using the Unleash proxy, using the Unleash front-end API has both benefits and drawbacks. The benefits are:
- Managing client-side API tokens is easier. With the Unleash proxy, you need to create and manage client keys manually; with the front-end API, you manage client-side API tokens in the exact same manner as other API tokens.
- You don't need to configure and run an Unleash proxy. The front-end API is part of Unleash itself and not an external process. All proxy clients will work exactly the same as they would with the Proxy.
On the other hand, using the front-end API has the following drawbacks compared to using the proxy:
- It can't handle a large number of requests per second. Because the front-end API is part of Unleash, you can't scale it horizontally the way you can scale the proxy.
- It sends client details to your Unleash instance. Unleash only stores these details in its short-term runtime cache, but this can be a privacy issue for some use cases.
These points make the Unleash front-end API best suited for development purposes and applications that don’t receive a lot of traffic, such as internal dashboards. However, because the API is identical to the Unleash proxy API, you can go from one to the other at any time. As such, you can start out by using the front-end API and switch to using the proxy when you need it.
Using the Unleash front-end API
When using the front-end API in an SDK, there's three things you need to configure.
Front-end API tokens
As a client-side API, you should use a front-end API token to interact with it. Refer to the how to create API tokens guide for steps on how to create API tokens.
Cross-origin resource sharing (CORS) configuration
You need to allow traffic from your application domains to use the Unleash front-end API with web and hybrid mobile applications. You can update the front-end API CORS settings from the Unleash UI under admin > CORS or by using the API.
API URL
The client needs to point to the correct API endpoint. The front-end API is available at <your-unleash-instance>/api/frontend.
API token
You can create appropriate token, with type FRONTEND on <YOUR_UNLEASH_URL>/admin/api/create-token page or with a request to /api/admin/api-tokens. See our guide on how to create API tokens for more details.
Refresh interval for tokens
Internally, Unleash creates a new Unleash client for each token it receives. Each client is configured with the project and environment specified in the token.
Each client updates its feature toggle configuration at a specified refresh interval plus a random offset between 0 and 10 seconds. By default, the refresh interval is set to 10 seconds. The random offset is used to stagger incoming requests to avoid a large number of clients all querying the database simultaneously. A new, random offset is used for every update.
The refresh interval is specified in milliseconds and can be set by using the FRONTEND_API_REFRESH_INTERVAL_MS environment variable or by using the frontendApi.refreshIntervalInMs configuration option in code.