SDKs
One engine, every major platform. Every SDK takes your server address, so nothing is tied to a hosted service.
Client-side and mobile SDKs#
Run in a browser or an app. They take a client key and receive only the result for one person.
Server-side SDKs#
Run in your backend. They take a server key, download the configuration and evaluate it in memory.
- Next.jsServer components, middleware and no-flicker client flags.
- Node.jsLocal evaluation with no network call per check.
- NestJSA module, a service and a route guard.
- GoStandard library only, safe for concurrent use.
- PythonBackground polling, thread-safe, standard library only.
- PHPA shared config cache for FPM, CLI and Octane.
- LaravelFacade, Blade @flag and route middleware.
- JavaBuilder client and a Spring Boot 3 starter.
- .NETASP.NET Core dependency injection and a route attribute.
Packages and requirements#
| SDK | Install | Needs | Reference |
|---|---|---|---|
| JavaScript | npm install @flagswift/js | Any modern browser | JavaScript reference |
| React | npm install @flagswift/react | React 18+ | React reference |
| React Native | npm install @flagswift/react-native | React Native 0.70+, AsyncStorage for the cache | React Native reference |
| Vue | npm install @flagswift/vue | Vue 3.3+ | Vue reference |
| Flutter | flutter pub add flagswift | Dart 3, Flutter 3.13+ | Flutter reference |
| Swift | Swift Package: FlagSwift | Swift 5.9, iOS 14+ | Swift reference |
| Next.js | npm install @flagswift/nextjs | Next.js 13.4+, React 18+ | Next.js reference |
| Node.js | npm install @flagswift/node | Node 18+ | Node.js reference |
| NestJS | npm install @flagswift/nestjs @flagswift/node | NestJS 9+, Node 18+ | NestJS reference |
| Go | go get github.com/flagswift/flagswift-go | Go 1.21+ | Go reference |
| Python | pip install flagswift | Python 3.8+ | Python reference |
| PHP | composer require flagswift/flagswift-php | PHP 8.1+ | PHP reference |
| Laravel | composer require flagswift/flagswift-laravel | Laravel 10 to 13 | Laravel reference |
| Java | Maven: io.flagswift:flagswift-java | Java 11+ (the Spring Boot starter needs Java 17) | Java reference |
| .NET | dotnet add package FlagSwift | .NET 8+ | .NET reference |
Compare SDKs#
Install command, what it needs and how far each SDK has been verified. Select a name for its reference page, or see SDK features for streaming, offline start and analytics side by side.
| SDK | Install | Requires | Verified |
|---|---|---|---|
| JavaScript | Install:npm install @flagswift/js | Requires:Any modern browser | Verified:Tested against shared vectors |
| React | Install:npm install @flagswift/react | Requires:React 18+ | Verified:Unit tests |
| React Native | Install:npm install @flagswift/react-native | Requires:React Native 0.70+, AsyncStorage for the cache | Verified:Unit tests |
| Vue | Install:npm install @flagswift/vue | Requires:Vue 3.3+ | Verified:Unit tests |
| Flutter | Install:flutter pub add flagswift | Requires:Dart 3, Flutter 3.13+ | Verified:Not yet compiled |
| Swift | Install:Swift Package: FlagSwift | Requires:Swift 5.9, iOS 14+ | Verified:Not yet compiled |
| Next.js | Install:npm install @flagswift/nextjs | Requires:Next.js 13.4+, React 18+ | Verified:Unit tests |
| Node.js | Install:npm install @flagswift/node | Requires:Node 18+ | Verified:Tested against shared vectors |
| NestJS | Install:npm install @flagswift/nestjs @flagswift/node | Requires:NestJS 9+, Node 18+ | Verified:Unit tests |
| Go | Install:go get github.com/flagswift/flagswift-go | Requires:Go 1.21+ | Verified:Tested against shared vectors |
| Python | Install:pip install flagswift | Requires:Python 3.8+ | Verified:Tested against shared vectors |
| PHP | Install:composer require flagswift/flagswift-php | Requires:PHP 8.1+ | Verified:Tested against shared vectors |
| Laravel | Install:composer require flagswift/flagswift-laravel | Requires:Laravel 10 to 13 | Verified:Tested against stand-ins for Laravel only |
| Java | Install:Maven: io.flagswift:flagswift-java | Requires:Java 11+ (the Spring Boot starter needs Java 17) | Verified:javac and JUnit only, no real Maven build |
| .NET | Install:dotnet add package FlagSwift | Requires:.NET 8+ | Verified:Not yet compiled |
Pick your platform#
// npm install @flagswift/react
import { FlagClient, FlagProvider, useFlag } from "@flagswift/react";
// Create the client once, outside components.
const client = new FlagClient({
apiKey: process.env.NEXT_PUBLIC_FLAGSWIFT_KEY!, // fs_client_...
baseUrl: "https://flags.example.com",
environment: "production", // only for project-wide keys
});
export const Providers = ({ children }) => (
<FlagProvider
client={client}
user={{ identifier: user?.id, account: user?.orgId, attributes: { plan: user?.plan } }}
>
{children}
</FlagProvider>
);
const Dashboard = () => (useFlag("new-dashboard") ? <NewDashboard /> : <OldDashboard />);Which key goes where#
| Runs in | Key | Description |
|---|---|---|
| Browser, mobile app | client key | Returns only enabled, variant and value for one person. Safe to ship. Used by React, React Native and the Next.js client provider. |
| Backend service | server key | Downloads the configuration and evaluates it locally. Private environment variable only. Used by Node.js, NestJS, Go, Python, PHP, Laravel, .NET and Next.js on the server. |
Common options#
| Option | Type | Description |
|---|---|---|
| apiKey* | string | The key for this app. Client or server, depending on the SDK. |
| baseUrl* | string | Your FlagSwift server address. There is no default host. |
| environment | string | Needed only when the key covers every environment of the project. |
| refreshInterval | ms | How often to check for changes. Default 30000; 0 turns polling off. |
| streaming | boolean | JavaScript, React, Next.js (client provider), Vue, Node, NestJS, Go, Python and Java: keep a real-time stream open and refresh the moment a flag changes. Default false. Falls back to polling by itself. |
| timeout | ms | Per request. Default 5000. |
| maxRetries | number | Retries with backoff for network errors and 5xx. Default 2. Never retries a 4xx. |
| fallbacks | { flagKey: value } | Served until flags load, when a flag is unknown, or when the server cannot be reached. |
| storage | getItem / setItem | Client SDKs only: offline cache for the last good flags, for example localStorage or AsyncStorage. |
| snapshotPath | string | Server SDKs: file that keeps the last good configuration (written atomically, owner-only) so a restart works while the server is down. Go, Python and .NET name it WithSnapshotPath, snapshot_path and SnapshotPath; PHP uses a FileStore. |
| reportErrors | boolean | Server SDKs report error counts, never user data, at most once a minute so they appear on the Errors page. Set false to turn off. |
| onError | function | Called for failures. SDKs never throw from a flag check. |
Identity#
A flag decides per person, so pass who they are. identifier is the user, account is their organization or tenant, and device is the install. A flag can roll out by any of the three. If a flag buckets by user and you pass none, it serves the off result with the reason NO_IDENTIFIER instead of guessing.
{ identifier: "user-123", account: "acme", device: "ios-7f3a", attributes: { plan: "pro", country: "NG" } }Notes by language#
| SDK | Requires | Description |
|---|---|---|
| Go | Go 1.21+ | Standard library only. Start(ctx) never aborts the app; call Close() on shutdown. The configuration is swapped atomically, so one client is safe to share across goroutines. |
| Python | 3.8+ | Standard library only. Polling runs on a background thread and the client is thread-safe. The 1.x names (check_flag, is_enabled(name, user_id=)) still work. |
| PHP | 8.1+ | PHP has no process to poll from, so the configuration lives in a store that requests share: FileStore works everywhere, ApcuStore shares memory inside one FPM pool, and ArrayStore suits queue workers and tests. A request with a warm cache never waits on a retry. |
| Laravel | 10 to 13 | Built on the PHP SDK with your Laravel cache as the store. Use a cache store your workers share. Run php artisan flagswift:refresh in a deploy hook and flagswift:status to see what is loaded. |
| .NET | .NET 8+ | Register the client as a singleton; the hosted service loads the configuration at startup and a failed first fetch does not stop the app. [RequireFlag] returns 404 when a flag is off. |
| Java | Java 11+ (Spring Boot starter: Java 17) | Build one client with FlagSwift.builder(), call initialize() at startup and close() at shutdown. It is thread-safe. The optional Spring Boot 3 starter configures it from flagswift.* in application.yml and adds @FeatureFlag, which answers 404 when a flag is off. |
Verification status
When something fails#
Flag checks never throw. Before the first response an SDK returns your fallback, then false. If a refresh fails, the last good flags keep serving. If a server speaks a newer hashing version than the SDK understands, the server SDKs refuse it rather than guessing.
Migrating from 1.x
@flagswift/react-client to @flagswift/react, @flagswift/node-server to @flagswift/node) and baseUrl is now required. The Python SDK moved from 1.x to 2.0.0: it keeps the v1 names but now needs base_url and a server or admin key. Go, PHP, Laravel and .NET are new. The full list is in sdks/MIGRATION.md in the SDK repository.