# Unleashsdk

> Use this skill when implementing feature flags and gradual rollouts in ColdBox/BoxLang using the unleashsdk module. Covers UnleashClient configuration, isEnabled() checks, getVariant() for A/B testing, custom context, gradual rollout strategies, and production patterns for safe feature releases.

- Skill: `coldbox/unleashsdk` (Agent Skill)
- Install (CLI): `npx skillmds@latest add coldbox/unleashsdk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/coldbox/unleashsdk/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ColdBox (https://skillmd.com/u/coldbox)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/coldbox/unleashsdk

---


# UnleashSDK Skill

## When to Use This Skill

Load this skill when:
- Enabling/disabling features at runtime without redeployment
- Rolling out features gradually to a percentage of users
- Running A/B tests or controlled experiments
- Creating killswitches for risky features
- Targeting feature flags to specific user segments

## Installation

```bash
box install unleashsdk
```

## Configuration

### config/modules/unleashsdk.cfc

```js
function configure() {
    return {
        // Unleash server URL
        url        : getSystemSetting( "UNLEASH_URL",    "https://unleash.example.com/api" ),
        // Client API token
        apiToken   : getSystemSetting( "UNLEASH_TOKEN",  "" ),
        // Application identifier — shown in Unleash UI
        appName    : getSystemSetting( "APP_NAME",       "myapp" ),
        // Environment (matches Unleash environment activation)
        environment: getSystemSetting( "APP_ENV",        "production" ),
        // How often to sync flags from server (seconds)
        refreshInterval : 15,
        // Cache TTL (seconds) — use cached values when server unreachable
        cacheTTL        : 60
    }
}
```

## Core API

### Injection

```js
property name="unleash" inject="UnleashClient@unleashsdk";
```

### Check if a Feature is Enabled

```js
// Simple check
if ( unleash.isEnabled( "new-dashboard" ) ) {
    // render new dashboard
}

// With context (user ID, session ID, properties)
if ( unleash.isEnabled( "beta-checkout", {
    userId    : security.getCurrentUser().getId(),
    sessionId : session.id,
    properties: {
        role  : security.getCurrentUser().getRole(),
        plan  : security.getCurrentUser().getPlan()
    }
} ) ) {
    // show beta checkout flow
}
```

### Get a Variant (A/B Testing)

```js
var variant = unleash.getVariant( "checkout-button-color", {
    userId : security.getCurrentUser().getId()
} )

// variant.name   = "blue" | "green" | "disabled"
// variant.enabled = true/false
// variant.payload = { type: "string", value: "#0070f3" }

if ( variant.enabled ) {
    prc.buttonColor = variant.payload.value
} else {
    prc.buttonColor = "default"
}
```

## Production Patterns

### Feature Flag in a Handler

```js
function checkout( event, rc, prc ) {
    var userId = security.getCurrentUser().getId()

    // Feature flag controls which checkout version to render
    if ( unleash.isEnabled( "new-checkout-v2", { userId: userId } ) ) {
        prc.layout = "v2"
        event.setView( "checkout/v2/index" )
    } else {
        prc.layout = "v1"
        event.setView( "checkout/v1/index" )
    }
}
```

### Gradual Rollout Service

```js
class FeatureService {

    property name="unleash" inject="UnleashClient@unleashsdk";

    boolean function useNewSearch() {
        return unleash.isEnabled( "new-search-engine", {
            userId    : security.getCurrentUser().getId(),
            sessionId : session.id
        } )
    }

    struct function getCheckoutVariant() {
        var variant = unleash.getVariant( "checkout-experiment", {
            userId : security.getCurrentUser().getId()
        } )
        return {
            name   : variant.enabled ? variant.name : "control",
            config : variant.enabled ? variant.payload : {}
        }
    }
}
```

### Killswitch / Emergency Disable

```js
function run( event, rc, prc ) {
    if ( !unleash.isEnabled( "data-export-feature" ) ) {
        event.renderData(
            type       = "json",
            statusCode = 503,
            data       = { error: "This feature is temporarily disabled." }
        )
        return
    }

    // ... proceed with export
}
```

### Automated A/B Test Tracking

```js
function trackAndRoute( event, rc, prc ) {
    var variant = unleash.getVariant( "pricing-page", {
        userId : security.getCurrentUser().getId()
    } )

    // Record which variant the user saw
    analyticsService.track( "pricing_variant_shown", {
        userId  : security.getCurrentUser().getId(),
        variant : variant.name
    } )

    if ( variant.name == "v2" ) {
        event.setView( "pricing/v2" )
    } else {
        event.setView( "pricing/v1" )
    }
}
```

## Best Practices

- **Always provide a default** — `isEnabled()` returns `false` if the server is unreachable; design safe defaults
- **Use user context** for consistent per-user bucketing in gradual rollouts
- **Use `getVariant()`** for experiments, not just `isEnabled()` — variants carry payload and support multi-arm tests
- **Store the API token in an environment variable** — never commit it to source control
- **Use feature flags as killswitches** for risky features — wrap expensive or experimental code paths
- **Clean up stale flags** — remove flags from code once a rollout is complete (100% or 0%)
- **Test the `false` path** — ensure the application works correctly when a flag is disabled

## Documentation

- unleashsdk: https://github.com/coldbox-modules/unleashsdk
- Unleash feature flags: https://docs.getunleash.io