Feature Flags

Feature flags are the foundation of Supaship. They let you control features at runtime without redeploying code. With flags, you can roll out safely, test with real users, and respond instantly if something breaks.

What are Feature Flags?

A feature flag is essentially a conditional switch in your code that Supaship controls. Instead of hardcoding “always show this feature,” you wrap it in a flag and let Supaship decide when to show it.

if (supaship.getFeature('new-checkout-flow', { fallback: false })) {
  // Show the new checkout
  renderNewCheckout()
} else {
  // Fall back to the old checkout
  renderOldCheckout()
}

Why use Feature Flags?

• Continuous Delivery – Ship code to production safely, even if it’s not ready for everyone.
• Targeted Rollouts – Control who sees what (e.g., 10% of users, or only those in India).
• Instant Rollbacks – Turn off a broken feature in seconds, no redeploy required.
• Progressive Delivery – Gradually roll out features in increments (eg: 1%, 10%, 50%, 100%) to reduce risk.

How to create a Feature Flag?

1. Select a Project: Navigate to the project where you want to add the flag.
2. Click on the “Create Feature Flag” button: This will open the flag creation form.
3. Enter the flag name: Give your flag a name. It should be in lowercase letters, with numbers, and hyphens.
4. Select a Type: Choose the type of flag you want to create. (Boolean, JSON)
5. Click on the “Create” button: This will create the feature flag. You will be redirected to the feature flag details page.

Flag Types

Boolean Flags

Simple on/off switches for feature control.

• Example: Toggle a new feature, beta banner, or bug fix.
• Variations: true or false.

import { SupaClient } from '@supashiphq/sdk-javascript'
 
const client = new SupaClient({
  environment: 'production', // your environment slug
  apiKey: '1234567890abcdef1234567890abcdef', // find it in the project settings
  context: { userID: '123' }, // user context
})
 
// Check if feature is enabled
const isEnabled = await client.getFeature('beta-banner', { fallback: false })
 
if (isEnabled) {
  showBetaBanner()
}

JSON Flags

Return complex objects for advanced configurations.

• Example: Default settings, API configuration, etc.

// Get JSON configuration
const config = await client.getFeature('api-config', {
  fallback: {
    timeout: 5000, // default timeout
    retries: 3, // default retries
    endpoint: '/api/v1', // default endpoint
  },
})
 
// Use in your application
const apiClient = new ApiClient(config)

Can I create STRING or NUMBER flags?

You can create a JSON flag and then set one the the properties to a string or number.

const settings = await client.getFeature('default-settings', {
  fallback: {
    discount: 10, // default discount percentage
    currency: 'USD', // default currency
  },
})

Note: For language specific examples, please refer to the code examples section.

Best Practices

Naming Conventions

• Use descriptive, lowercase names with hyphens
• Use a period to group related flags
• Examples: new-checkout-flow, beta-features, dark-mode

Monitoring and Analytics

Track Feature Usage

Monitor how your features are being used:

• Real-time metrics - Live feature usage data
• User engagement - Track how features affect behavior
• Performance monitoring - Monitor flag evaluation times
• Custom events - Track specific user actions