Quick Start Guide

Get started with Supaship in minutes. This guide will walk you through creating your first organization, project, and feature flag.

Prerequisites

A Supaship account (sign up at supaship.com )
Basic knowledge of your programming language
A web browser for testing

Step 1: Set Up Your Organization

When you sign up, a default organization is automatically created for you. You can create additional organizations as needed.

Sign in to your Supaship dashboard.
Create an organization - This represents your company, department, or team

Invite team members if needed with appropriate roles:

OWNER - Full administrative rights, including managing members, projects, and billing
MEMBER - Can work within projects but with limited administrative privileges

Step 2: Create Your First Project

A Project represents a software application or service where your feature flags will live.

Navigate to your organization dashboard
Click “Create Project”
Enter a project name (e.g., “My Web App”)
Configure your project settings

By default, Supaship creates two environments for each project:

Development - For local development and testing
Production - For live applications

You can add more environments (like staging) as needed.

Step 3: Create Your First Feature Flag

Navigate to the Features section within your project
Click “Create Feature Flag” button
Enter a flag name following the naming convention:
- Use lowercase letters, numbers, and hyphens
- Examples: new-checkout-flow, dark-mode, premium-features
Select a flag type:
- Boolean - Simple on/off flags (true/false)
- JSON - Flexible configurations for advanced scenarios
Click “Create” to create the feature flag

Step 4: Get Your API Keys

Each project has API keys for authentication. There are two types:

Client Keys - Used in frontend/client-side apps (safe to expose publicly)
Server Keys - Used in backend services (keep these secret)

Go to your project settings
Navigate to the API Keys section
Copy the appropriate API key for your environment:
- Use Client Key for browser/mobile apps
- Use Server Key for backend services

Your API key will look like this:


1234567890abcdef1234567890abcdef-client

Note: API keys are 32-character identifiers without any prefixes. Both key types work across all environments within the project.

Step 5: Install the SDK

Choose your preferred language and install the Supaship SDK:

JavaScript/TypeScript (Client-side)


npm install @supaship/sdk-javascript

Step 6: Initialize the SDK

Add the SDK to your application:

JavaScript/TypeScript (Client-side)


import { SupaClient } from '@supaship/sdk-javascript'
 
const client = new SupaClient({
  apiKey: process.env.SUPASHIP_API_KEY, // Your project's client key
  environment: 'production', // Environment slug
  context: {
    userID: 'slp8um4smczngfy', // User identifier (required for percentage rollouts)
    email: '[email protected]',
    appVersion: '1.0.5',
  },
})
 
// Check if a feature is enabled
const isEnabled = await client.getFeature('new-navigation', { fallback: false })
console.log('New navigation enabled:', isEnabled)

For more examples, please refer to the code examples section for your language/framework.

Step 7: Add User Targeting

Targeting allows you to control who sees your feature based on user attributes:

Go to your feature details page.
Select the environment you want to configure from the left sidebar.
Click “Add Rule”
Configure the targeting rule:
- Criteria: Choose a context property (e.g., “email”, “userID”, “country”)
- Operator: Select the condition (e.g., “contains”, “equals”, “greater than”)
- Value: Enter the target value (e.g., “admin”)
Set a percentage rollout if needed (e.g., 50% of matching users)
Save the rule

This will enable the feature only for users matching your targeting criteria.

Step 8: Test with Different Users


// Test with admin user
const adminEnabled = await client.getFeature('new-navigation', {
  fallback: false,
  context: {
    userID: 'admin-user-123',
    email: '[email protected]',
  },
})
console.log('Admin enabled:', adminEnabled) // true
 
// Test with regular user
const userEnabled = await client.getFeature('new-navigation', {
  fallback: false,
  context: {
    userID: 'regular-user-456',
    email: '[email protected]',
  },
})
console.log('User enabled:', userEnabled) // false

Step 9: Environment Variables (Recommended)

For production applications, store your API key in environment variables:

Client-side (React/Next.js)


# .env.local
REACT_APP_SUPASHIP_API_KEY=1234567890abcdef1234567890abcdef-client
# or for Next.js
NEXT_PUBLIC_SUPASHIP_API_KEY=1234567890abcdef1234567890abcdef-client


const client = new SupaClient({
  apiKey: process.env.REACT_APP_SUPASHIP_API_KEY, // or NEXT_PUBLIC_SUPASHIP_API_KEY
  context: {
    userID: 'slp8um4smczngfy',
    email: '[email protected]',
  },
})