> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stringboot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from 2.x

> Move your web app from @stringboot/web-sdk 2.x to 3.0

***

> [!WARNING]
>
> **This upgrade is required.** The endpoints Web SDK 2.x uses now answer `426 Upgrade Required`. Sites running 2.x keep showing what they cached but receive no further updates until you deploy 3.0.1 or later.

## 1. Update the package

```bash theme={null}
npm install @stringboot/web-sdk@^3.0.1
```

## 2. Use a Client Token

Pass your App's **Client Token** (`sb_...`) as `apiToken`. Create one in the dashboard (see [API Tokens](https://docs.stringboot.com/dashboard-guides/api-tokens.md)). The token now travels in the URL path, not in an `X-API-Token` or `Authorization` header. A Figma Plugin Token, or a revoked or expired token, gets `401 invalid_token`.

## 3. Review the behaviour changes

### `initialize()` resolves earlier

This is the change most likely to affect your code. With a Catalog stored from an earlier visit, `initialize()` now resolves **as soon as that Catalog is applied**; the `/languages` and version checks finish in the background. On a first visit it still waits for the download.

If your code assumes "`initialize()` resolved" means "synced with the server", wait for the start-up checks explicitly:

```javascript theme={null}
await StringBoot.initialize({ apiToken: 'sb_YOUR_CLIENT_TOKEN' });
await StringBoot.waitForStartupSync();   // never rejects
```

Errors found after start-up, such as a rejected token, arrive through `onSyncError`. In React, `useStringBoot().error` reports them too.

```javascript theme={null}
const off = StringBoot.onSyncError((error) => {
  if (error.code === 'INVALID_TOKEN') showTokenBanner();
});
```

### Other changes

| Area | What changed |
| :- | :- |
| **Device-ID** | Every request carries a `Device-ID`, generated and stored by the SDK. Pass `deviceId` only to use your own. |
| **FAQs** | Come with the Catalog. Remove `StringBoot.FAQ.initialize(...)`; it's accepted but does nothing once the SDK is initialized. |
| **Experiments** | Bucketed in the browser with the same function the server used. 2.x didn't send a Device-ID, so web users get a new one and may land in a different variant once; pass your previous user id as `deviceId` if you need continuity. `onExperimentsAssigned` still works and is now called with `{}` when experiments stop. Add `onExposure` to report exposures. |
| **Periodic checks** | New: every 60 seconds by default (`refreshInterval`), paused while the tab is hidden. |
| **Fallback** | A key missing from the selected language falls back to the App's default language before `??key??`. |
| **Escapes** | `\n`, `\t`, `\r`, `\"`, `\'` and `\\` in string values are unescaped, as on mobile. Use `white-space: pre-line` to show line breaks. |
| **Language codes** | Matched exactly as listed in the dashboard (for example `pt-BR`), no longer cut to two letters. `ActiveLanguage` gains `nativeName` and `direction`. |
| **React** | `useString` and `useStrings` render the cached value on their first render instead of briefly showing `??key??`. |
| **Integrity checks** | `enableIntegrityCheck` is accepted and ignored. |

### Removed types

`MetaResponse`, `DeltaResponse`, `CatalogResponse`, `ApiResponse`, `SyncMetadata`, `CachedString`, `FAQMetaResponse`, `FAQDeltaResponse` and `FAQCatalogResponse`. Use `Catalog`, `LanguagesResponse` and `CurrentVersionResponse` instead.

## What happens to returning visitors

On the first start, 3.0 deletes the data 2.x stored in the browser and downloads the strings once.

## Checklist

* [ ] `@stringboot/web-sdk` is `3.0.1` or later
* [ ] `apiToken` is a Client Token starting with `sb_`
* [ ] Code that needs fresh server data waits for `waitForStartupSync()`
* [ ] Errors after start-up are handled with `onSyncError` (or `useStringBoot().error`)
* [ ] Analytics code handles an empty assignments object
* [ ] `StringBoot.FAQ.initialize(...)` calls are removed
* [ ] A first visit shows your strings, and an edit in the dashboard appears within about two minutes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.