Skip to content
FlagSwiftDocs

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#

Server-side SDKs#

Packages and requirements#

SDKInstallNeedsReference
JavaScriptnpm install @flagswift/jsAny modern browserJavaScript reference
Reactnpm install @flagswift/reactReact 18+React reference
React Nativenpm install @flagswift/react-nativeReact Native 0.70+, AsyncStorage for the cacheReact Native reference
Vuenpm install @flagswift/vueVue 3.3+Vue reference
Flutterflutter pub add flagswiftDart 3, Flutter 3.13+Flutter reference
SwiftSwift Package: FlagSwiftSwift 5.9, iOS 14+Swift reference
Next.jsnpm install @flagswift/nextjsNext.js 13.4+, React 18+Next.js reference
Node.jsnpm install @flagswift/nodeNode 18+Node.js reference
NestJSnpm install @flagswift/nestjs @flagswift/nodeNestJS 9+, Node 18+NestJS reference
Gogo get github.com/flagswift/flagswift-goGo 1.21+Go reference
Pythonpip install flagswiftPython 3.8+Python reference
PHPcomposer require flagswift/flagswift-phpPHP 8.1+PHP reference
Laravelcomposer require flagswift/flagswift-laravelLaravel 10 to 13Laravel reference
JavaMaven: io.flagswift:flagswift-javaJava 11+ (the Spring Boot starter needs Java 17)Java reference
.NETdotnet 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.

Install, requirements and verification status of every SDK
SDKInstallRequiresVerified
JavaScriptInstall:npm install @flagswift/jsRequires:Any modern browserVerified:Tested against shared vectors
ReactInstall:npm install @flagswift/reactRequires:React 18+Verified:Unit tests
React NativeInstall:npm install @flagswift/react-nativeRequires:React Native 0.70+, AsyncStorage for the cacheVerified:Unit tests
VueInstall:npm install @flagswift/vueRequires:Vue 3.3+Verified:Unit tests
FlutterInstall:flutter pub add flagswiftRequires:Dart 3, Flutter 3.13+Verified:Not yet compiled
SwiftInstall:Swift Package: FlagSwiftRequires:Swift 5.9, iOS 14+Verified:Not yet compiled
Next.jsInstall:npm install @flagswift/nextjsRequires:Next.js 13.4+, React 18+Verified:Unit tests
Node.jsInstall:npm install @flagswift/nodeRequires:Node 18+Verified:Tested against shared vectors
NestJSInstall:npm install @flagswift/nestjs @flagswift/nodeRequires:NestJS 9+, Node 18+Verified:Unit tests
GoInstall:go get github.com/flagswift/flagswift-goRequires:Go 1.21+Verified:Tested against shared vectors
PythonInstall:pip install flagswiftRequires:Python 3.8+Verified:Tested against shared vectors
PHPInstall:composer require flagswift/flagswift-phpRequires:PHP 8.1+Verified:Tested against shared vectors
LaravelInstall:composer require flagswift/flagswift-laravelRequires:Laravel 10 to 13Verified:Tested against stand-ins for Laravel only
JavaInstall:Maven: io.flagswift:flagswift-javaRequires:Java 11+ (the Spring Boot starter needs Java 17)Verified:javac and JUnit only, no real Maven build
.NETInstall:dotnet add package FlagSwiftRequires:.NET 8+Verified:Not yet compiled

Pick your platform#

React
// 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#

Key type for each kind of code
Runs inKeyDescription
Browser, mobile appclient keyReturns only enabled, variant and value for one person. Safe to ship. Used by React, React Native and the Next.js client provider.
Backend serviceserver keyDownloads 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#

Options shared by the SDKs
OptionTypeDescription
apiKey*stringThe key for this app. Client or server, depending on the SDK.
baseUrl*stringYour FlagSwift server address. There is no default host.
environmentstringNeeded only when the key covers every environment of the project.
refreshIntervalmsHow often to check for changes. Default 30000; 0 turns polling off.
streamingbooleanJavaScript, 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.
timeoutmsPer request. Default 5000.
maxRetriesnumberRetries 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.
storagegetItem / setItemClient SDKs only: offline cache for the last good flags, for example localStorage or AsyncStorage.
snapshotPathstringServer 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.
reportErrorsbooleanServer SDKs report error counts, never user data, at most once a minute so they appear on the Errors page. Set false to turn off.
onErrorfunctionCalled 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.

ts
{ identifier: "user-123", account: "acme", device: "ios-7f3a", attributes: { plan: "pro", country: "NG" } }

Notes by language#

What differs from the JavaScript SDKs
SDKRequiresDescription
GoGo 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.
Python3.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.
PHP8.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.
Laravel10 to 13Built 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.
JavaJava 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

The JavaScript, Go, Python and PHP SDKs have been tested against the shared evaluation vectors. The .NET SDK has not been compiled or run yet, the Java SDK was tested with javac and JUnit but not a real Maven build (its Spring Boot starter only against stand-ins), and the Laravel package has only been tested against stand-ins for Laravel itself. Smoke-test either against your own server before relying on it in production.

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

Rollout buckets differ from the first-generation SDKs, so a person can land on the other side of a percentage rollout once after upgrading, then it is stable. Packages were renamed (@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.