# Backend-Driven Configuration

# Backend-Driven Configuration

The Frak SDK supports dynamic configuration resolved from the backend. When your application initializes, the SDK fetches your merchant configuration from the Frak backend based on your domain. This means you can manage branding, translations, component settings, and [placements](/developers/concepts/placements) directly from the [business dashboard](/guides/dashboard) without redeploying your application.

## How It Works

1. **SDK Initialization** — When the SDK starts, it calls the Frak backend's resolve endpoint with your domain.
2. **Merchant Resolution** — The backend identifies your merchant account and returns the associated configuration.
3. **Config Merging** — The resolved backend config is merged with your local SDK config. Backend values take priority over local values.
4. **Reactive Updates** — Components automatically re-render when the backend configuration is resolved.

```
Your Website                    Frak Backend
    |                               |
    |  GET /resolve?domain=...      |
    |------------------------------>|
    |                               |
    |  { merchantId, sdkConfig }    |
    |<------------------------------|
    |                               |
    | Components update reactively  |
    |                               |
```

## Configuration Priority

The SDK merges configuration from multiple sources. When the same setting exists at multiple levels, the highest-priority source wins:

1. **Backend config** (highest priority) — Set in the business dashboard
2. **SDK static config** — Passed in your `FrakWalletSdkConfig` object
3. **Defaults** — Built-in SDK defaults

This means you can set sensible defaults in your code and override them from the dashboard without touching your codebase.

## Resolved Configuration

The backend returns the following fields when available:

| Field | Description |
|-------|-------------|
| `name` | Your application display name |
| `logoUrl` | Logo URL displayed in modals and components |
| `homepageLink` | Link to your homepage (used in some components) |
| `currency` | Display currency (`"eur"`, `"usd"`, `"gbp"`) |
| `lang` | Language override (`"en"`, `"fr"`) |
| `hidden` | When `true`, all SDK components are hidden |
| `css` | Global CSS applied to modals and components |
| `translations` | Global translation overrides |
| `placements` | Named placement configurations (see [Placements](/developers/concepts/placements)) |
| `components` | Global component defaults |

## Controlling Loading Behavior

By default, the SDK waits for the backend configuration to be resolved before rendering components. This ensures components display the correct branding and settings from the start.

You can control this behavior with the `waitForBackendConfig` option:

```ts twoslash
// @noErrors
import type { FrakWalletSdkConfig } from '@frak-labs/core-sdk';

const config: FrakWalletSdkConfig = {
  metadata: {
    name: "My App",
  },
  // When true (default): components show a loading spinner until backend config is resolved
  // When false: components render immediately with local config / HTML attributes
  waitForBackendConfig: true,
};
```

:::tip
Keep `waitForBackendConfig: true` (the default) if you rely on backend-managed settings like translations, custom CSS, or placements. Set it to `false` if you provide all configuration locally and want instant rendering.
:::

## Caching

The SDK caches the resolved configuration in `localStorage` with a 30-second TTL using a stale-while-revalidate strategy:

- **Fresh cache** (< 30 seconds): The cached config is used immediately, no network request.
- **Stale cache** (> 30 seconds): The cached config is used immediately for fast rendering, while a background fetch updates the cache.
- **No cache**: A network request is made and components wait for the response (or render immediately if `waitForBackendConfig` is `false`).

The cache is scoped per domain and language, so different subdomains or language settings maintain separate caches.

## Managing Backend Configuration

Backend-driven configuration is managed from the **business dashboard**. Navigate to your merchant's settings to configure:

- **Branding** — Name, logo, homepage link
- **Display** — Language, currency, visibility toggle
- **Styling** — Custom CSS for modals and components
- **Translations** — Override default text for any SDK component
- **Placements** — Create named configurations for different sections of your site (see [Placements](/developers/concepts/placements))

Changes made in the dashboard take effect on your website within 30 seconds (the cache TTL), without requiring any code changes or redeployment.