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.

1. Navigate to your organization dashboard
2. Click “Create Project”
3. Enter a project name (e.g., “My Web App”)
4. 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

1. Navigate to the Features section within your project
2. Click “Create Feature Flag” button
3. Enter a flag name following the naming convention:
   • Use lowercase letters, numbers, and hyphens
   • Examples: new-checkout-flow, dark-mode, premium-features
4. Select a flag type:
   • Boolean - Simple on/off flags (true/false)
   • JSON - Flexible configurations for advanced scenarios
5. 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)

1. Go to your project settings
2. Navigate to the API Keys section
3. 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 @supashiphq/javascript-sdk

Step 6: Initialize the SDK

Add the SDK to your application:

JavaScript/TypeScript (Client-side)

import { SupaClient } from '@supashiphq/javascript-sdk'
 
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',
  },
  features: {
    'new-navigation': false,
  },
})
 
// Check if a feature is enabled
const isEnabled = await client.getFeature('new-navigation')
console.log('New navigation enabled:', isEnabled)

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

Step 7: Configure Targeting

Control who sees your feature with targeting rules:

1. Open your feature flag → Targeting section
2. Select the environment (development/production)
3. Click “Add Rule”
4. Configure:
   • Attribute: Choose a context property (e.g., email, country)
   • Operator: Select condition (e.g., equals, contains)
   • Value: Enter target value (e.g., [email protected])
5. Optional: Set percentage rollout (e.g., 50% of matching users)
6. Save

The feature will only be enabled for users matching your criteria.

Step 8: Test with Different Users

// Test with admin user
const adminEnabled = await client.getFeature('new-navigation', {
  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', {
  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]',
  },
})