Skip to Content
Client-Side Code ExamplesJavaScript / TypeScript

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/sdk-javascript

ES6 Module Import

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

CDN (Browser)

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

Quick Start

Basic Usage

This example shows how to get a feature flag with a fallback value.

  • fallback - The value to return if the feature flag is not found or targeting is not enabled.
import { SupaClient } from '@supashiphq/sdk-javascript'
 
const client = new SupaClient({
  apiKey: YOUR_PROJECT_API_KEY, // Client API Key, found in your project settings
  environment: 'production', // Environment slug
  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 with fallback
const isEnabled = await client.getFeature('new-navigation', { fallback: false })
 
if (isEnabled) {
  console.log('New navigation is enabled!')
} else {
  console.log('Using old navigation')
}

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.

  • fallback - The value to return if the feature flag is not found.
  • context - The context to use for the specific feature flag evaluation.
import { SupaClient } from '@supashiphq/sdk-javascript'
 
const client = new SupaClient({
  apiKey: YOUR_PROJECT_API_KEY, // Client API Key, found in your project settings
  environment: 'production', // Environment slug
  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', {
  fallback: false,
  context: { plan: 'premium' },
})
 
console.log('Feature enabled:', featureEnabled)

API Reference

Constructor

const client = new SupaClient(config)

Parameters:

  • config (object) - Configuration object

Config Options:

  • apiKey (string) - Your Supaship client API key
  • environment (string) - The environment slug (e.g., ‘production’, ‘staging’, ‘development’)
  • context (object, optional) - Default user context for all requests
  • networkConfig (object, optional) - Network settings including endpoints, retry configurations, timeout, and custom fetch functions

Methods

getFeature(featureKey, options)

Gets single feature flag value. Returns a boolean or object if the flag is a JSON type.

// Basic usage with fallback
const isEnabled = await client.getFeature('new-feature', { fallback: false })
// isEnabled is a boolean (true or false)
 
// With context override
const value = await client.getFeature('feature-name', {
  fallback: false,
  context: { plan: 'premium' },
})
 
// JSON configuration
const config = await client.getFeature('api-config', {
  fallback: { timeout: 5000, retries: 3, endpoint: '/api/v1' },
})
// config is an object

getFeatures(features, options)

Get multiple feature flags at once. Returns an object with the feature flag names as keys and the flag values as values.

// Get multiple features
const features = await client.getFeatures({
  features: {
    'new-navigation': false, // fallback is false
    'api-config': { timeout: 5000, retries: 3, endpoint: '/api/v1' }, // fallback object
  },
  context: {
    userID: '456', // Override default context for this request
  },
})
 
console.log(features)
// { 'new-navigation': true, 'api-config': { ... } }

setContext(context)

Update the default context for all subsequent requests. This context is used for all feature flag evaluations unless overridden by the context parameter in the getFeature or getFeatures methods.

This helpful when the context data is not available at the time of client initialization, and you need to wait for async data to be available before evaluating feature flags.

const client = new SupaClient({
  apiKey: YOUR_PROJECT_API_KEY, // Client API Key, found in your project settings
  environment: 'production', // Environment slug
  context: {}, // Empty context
})
 
const context = await apiCallToGetContext()
// Updates the default context for all subsequent requests
client.setContext(context)
 
// All subsequent getFeature calls will use the updated context
const isEnabled = await client.getFeature('new-navigation', {
  fallback: false,
})

getContext()

Get the current default context. Returns an object with the current context data.

const context = client.getContext()
console.log('Current context:', context)

Usage examples

Vanilla JavaScript (browser)

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