FlagLite SDK

Simple, fast feature flags for JavaScript and TypeScript. Go from signup to evaluating your first flag in under 30 seconds.

Installation

npm install flaglite

Quick Start

Using Environment Variable (Recommended)

Set your API key in the environment:

export FLAGLITE_API_KEY=fl_env_xxxxx

Then use the simple import:

import flags from 'flaglite'

if (await flags.enabled('new-checkout')) {
  showNewCheckout()
}

Explicit Initialization

import { FeatureFlags } from 'flaglite'

const flags = new FeatureFlags('fl_env_xxxxx')

if (await flags.enabled('new-checkout')) {
  showNewCheckout()
}

With User ID (Percentage Rollouts)

For sticky percentage rollouts, pass a user ID:

if (await flags.enabled('new-checkout', { userId: user.id })) {
  showNewCheckout()
}

The same user always gets the same result for the same flag.

Browser Usage (CDN)

No build step required:

<script src="https://cdn.flaglite.dev/sdk.min.js"></script>
<script>
  const flags = new FlagLite('fl_env_xxxxx')

  flags.enabled('new-checkout').then(enabled => {
    if (enabled) {
      showNewCheckout()
    }
  })
</script>

Configuration

import { FeatureFlags } from 'flaglite'

const flags = new FeatureFlags({
  apiKey: 'fl_env_xxxxx',
  baseUrl: 'https://api.flaglite.dev/v1', // default
  cacheTtl: 30000, // 30 seconds (default)
  prefetch: true, // prefetch all flags on init (default)
  timeout: 5000, // request timeout in ms (default)
})

API

flags.enabled(key, options?)

Check if a feature flag is enabled.

• key (string): The flag key (e.g., 'new-checkout')
• options.userId (string, optional): User ID for sticky percentage rollouts
• Returns: Promise<boolean> - true if enabled, false otherwise

Always returns false on error (fail closed).

flags.isEnabled(key, options?)

Alias for enabled().

flags.clearCache()

Clear the local flag cache.

flags.waitForInit()

Wait for the initial prefetch to complete.

How It Works

1. Caching: Flags are cached locally for 30 seconds (configurable)
2. Prefetching: All flags are fetched on init to reduce latency
3. Fail Closed: Returns false on any error
4. Sticky Bucketing: Same user always gets the same result using MurmurHash3

TypeScript

Full TypeScript support included:

import flags, { FeatureFlags, EvaluateOptions } from 'flaglite'

const options: EvaluateOptions = { userId: 'user-123' }
const enabled: boolean = await flags.enabled('new-checkout', options)

CI/CD

This package uses automated CI/CD:

• CI: Runs on every push/PR - linting, type checking, tests across Node 18/20/22
• Release: Tag with v* (e.g., git tag v1.0.0 && git push --tags) to publish to npm

Required repository secrets for releases:

• NPM_TOKEN - npm automation token with publish access

License

MIT