Migrate from Unleash

Overview

Unleash is a popular open-source feature toggle system. The core mental model — toggles with activation strategies — maps cleanly to ShipSilently’s flags and targeting rules. The biggest change is moving from self-hosted infrastructure to a fully managed service.

Before you begin

• You have a running Unleash server (self-hosted or Unleash Cloud) with toggles in production
• You have a ShipSilently account (create one free)
• Your application uses the Unleash Node.js client or another Unleash SDK

Step 1: Set up your ShipSilently project

1. Sign in to ShipSilently and create a new project.
2. Copy your API key from Settings → API Keys.

Step 2: Map Unleash concepts to ShipSilently

Unleash	ShipSilently
Toggle	Flag
isEnabled(name)	getFlag(key, context)
Activation Strategy	Targeting Rule
Context (userId, sessionId, etc.)	Evaluation context object
Project	Project
Environment	Environment

Step 3: Export your toggles

In Unleash, note down each toggle name and its activation strategies. You’ll recreate these as flags and targeting rules in ShipSilently.

For complex strategies like gradualRolloutUserId, you’ll configure equivalent percentage rollouts in ShipSilently targeting rules.

Step 4: Recreate your flags in ShipSilently

For each Unleash toggle:

1. Create a flag in ShipSilently with the same toggle name as the key
2. Replicate activation strategies as targeting rules:
   • userWithId → “Match specific user IDs” targeting rule
   • gradualRolloutUserId → Percentage rollout targeting rule
   • remoteAddress → IP/region-based targeting rule
   • default → Always-on flag

Step 5: Replace the SDK

# Remove Unleash client
npm uninstall unleash-client

# Install ShipSilently
npm install @shipsilently/node

Step 6: Update initialization

Before (Unleash):

import { initialize } from 'unleash-client';

initialize({
  url: 'https://unleash.internal.example.com/api',
  appName: 'my-app',
  customHeaders: { Authorization: process.env.UNLEASH_API_TOKEN },
});

After (ShipSilently):

import { initialize } from '@shipsilently/node';

export const flags = initialize(process.env.SHIPSILENTLY_KEY);

Step 7: Update toggle evaluations

Before (Unleash):

import { isEnabled } from 'unleash-client';

const showNewUI = isEnabled('new-ui', {
  userId: user.id,
  sessionId: req.sessionID,
  remoteAddress: req.ip,
});

After (ShipSilently):

const showNewUI = await flags.getFlag('new-ui', {
  userId: user.id,
  sessionId: req.sessionID,
  remoteAddress: req.ip,
});

The context shape is nearly identical — ShipSilently accepts any key-value pairs, so you can pass the same fields you used in Unleash.

Step 8: Remove infrastructure

Once you’ve fully migrated:

1. Remove UNLEASH_API_TOKEN and Unleash URL from your config
2. Uninstall unleash-client
3. Shut down your Unleash server (if self-hosted) or cancel your Unleash Cloud subscription

What’s next

• No more Unleash server to maintain — ShipSilently is fully managed
• Read the ShipSilently SDK docs
• Set up your team in Settings → Team
• Explore the REST API for programmatic flag management