JavaScript / TypeScript

The Supaship JavaScript SDK lets you evaluate feature flags directly in your frontend applications. This enables you to control feature flags, rollouts, and UI changes without redeploying code.

This guide covers browser-based usage only. For Node.js or server-side usage, see the Node.js code examples.

Requirements

Modern browsers (ES6+ support)
A Client API Key for the environment you’re targeting (never expose a server key in browser code)
Supaship project with at least one feature flag created

Installation

pnpm add @supashiphq/javascript-sdk

ES6 Module Import


import { SupaClient, FeaturesWithFallbacks } from '@supashiphq/javascript-sdk'

CDN (Browser)


<!-- Option 1: ES6 Modules (Modern browsers) -->
<script type="module">
  import {
    SupaClient,
    FeaturesWithFallbacks,
  } from 'https://cdn.skypack.dev/@supashiphq/javascript-sdk'
</script>
 
<!-- Option 2: Global variable via esm.sh (works in all browsers) -->
<script src="https://esm.sh/@supashiphq/javascript-sdk?bundle&global=Supaship"></script>

Quick Start

Basic Usage

This example shows how to get feature flags with type-safe feature definitions.


import { SupaClient, FeaturesWithFallbacks } from '@supashiphq/javascript-sdk'
 
// Define your features with fallback values
const FEATURE_FLAGS = {
  'new-ui': false,
  'premium-features': false,
  'theme-config': {
    primaryColor: '#007bff',
    darkMode: false,
  },
} satisfies FeaturesWithFallbacks
 
const client = new SupaClient({
  apiKey: YOUR_PROJECT_API_KEY, // Client API Key, found in your project settings
  environment: 'production', // Environment slug
  features: FEATURE_FLAGS,
  context: {
    userID: '123', // User identifier (ex: userID, username, email, etc.), required for percentage rollouts
    email: '[email protected]',
    appVersion: '1.0.0',
  },
})
 
// Get a single feature flag (returns the type defined in features)
const isEnabled = await client.getFeature('new-ui')
// Returns: boolean
 
if (isEnabled) {
  console.log('New UI is enabled!')
} else {
  console.log('Using old UI')
}
 
// Get a configuration object
const themeConfig = await client.getFeature('theme-config')
// Returns: { primaryColor: string, darkMode: boolean }
console.log('Theme:', themeConfig.primaryColor)

With Context Override

This example shows how to get a feature flag with a context override. A context can be used to override the default context (provided to client constructor) for a single request.


import { SupaClient, FeaturesWithFallbacks } from '@supashiphq/javascript-sdk'
 
const FEATURE_FLAGS = {
  'new-navigation': false,
  'premium-navigation': false,
} satisfies FeaturesWithFallbacks
 
const client = new SupaClient({
  apiKey: YOUR_PROJECT_API_KEY, // Client API Key, found in your project settings
  environment: 'production', // Environment slug
  features: FEATURE_FLAGS,
  context: {
    userID: '123', // User identifier (ex: userID, username, email, etc.), required for percentage rollouts
    email: '[email protected]',
  },
})
 
// Get a feature flag with context override
const featureEnabled = await client.getFeature('premium-navigation', {
  context: { plan: 'premium' },
})
 
console.log('Feature enabled:', featureEnabled)

API Reference

For complete API documentation, see the JavaScript SDK API Reference.

Usage Examples

Vanilla JavaScript (browser)


// app.js
import { SupaClient, FeaturesWithFallbacks } from '@supashiphq/javascript-sdk'
 
const FEATURE_FLAGS = {
  'new-navigation': false,
  'dark-mode': false,
  'premium-features': false,
} satisfies FeaturesWithFallbacks
 
const client = new SupaClient({
  apiKey: import.meta.env.VITE_SUPASHIP_API_KEY,
  environment: 'production',
  features: FEATURE_FLAGS,
  context: {
    userID: getCurrentUserId(),
    email: getCurrentUserEmail(),
  },
})
 
// Initialize features
async function initializeFeatures() {
  const results = await client.getFeatures([
    'new-navigation',
    'dark-mode',
    'premium-features',
  ])
 
  applyFeatures(results)
}
 
function applyFeatures(results) {
  if (results['new-navigation']) {
    document.body.classList.add('new-nav')
  }
 
  if (results['dark-mode']) {
    document.body.classList.add('dark-theme')
  }
 
  if (results['premium-features']) {
    showPremiumFeatures()
  }
}
 
// Initialize on page load
document.addEventListener('DOMContentLoaded', initializeFeatures)

React Integration

For React applications, use our dedicated React SDK which provides hooks and components optimized for React:

📦 @supashiphq/react-sdk

TypeScript Type Safety


import { SupaClient, FeaturesWithFallbacks } from '@supashiphq/javascript-sdk'
 
// Define features with proper typing
const FEATURE_FLAGS = {
  'new-dashboard': false,
  'theme-settings': {
    mode: 'light' as 'light' | 'dark',
    primaryColor: '#007bff',
  },
  'beta-features': false,
} satisfies FeaturesWithFallbacks
 
const client = new SupaClient({
  apiKey: import.meta.env.VITE_SUPASHIP_API_KEY,
  environment: 'production',
  features: FEATURE_FLAGS,
})
 
// TypeScript knows the exact types!
const themeSettings = await client.getFeature('theme-settings')
// Type: { mode: 'light' | 'dark'; primaryColor: string; }
 
const mode: 'light' | 'dark' = themeSettings.mode // ✅ Type-safe