SDK Integration Guide

Installation

Install the @flagpilot/javascript package:

npm install @flagpilot/javascript

Quick start

Initialize the client with your API key and evaluate flags. The SDK evaluates flags from an in-process cache on first access, with automatic refresh via Edge Config webhooks.

import { FlagPilot } from '@flagpilot/javascript';

const flagpilot = new FlagPilot({
  clientKey: 'fk_client_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  environment: 'production'
});

await flagpilot.initialize();

// Evaluate a feature flag
const isEnabled = flagpilot.evaluate('checkout-redesign', {
  userId: 'user_123'
});

if (isEnabled) {
  // Render new checkout experience
}

Target users

Pass a stable, opaque user identifier with every evaluation. If this identifier matches a user ID in the **Target Users** list inside your dashboard, the flag will immediately resolve to true (bypassing any percentage rollout).

const isEnabled = await flagpilot.evaluate('checkout-redesign', {
  userId: 'user_123',
  plan: 'pro'
});

Error handling

Wrap initialization and evaluation in your app's normal error boundary or logging layer. Use a conservative fallback when the SDK cannot resolve a flag.

let isEnabled = false;
try {
  isEnabled = await flagpilot.evaluate('checkout-redesign', { userId: 'user_123' });
} catch {
  isEnabled = false;
}

Best practices

• Initialize one SDK client per application runtime and reuse it across requests or renders.
• Use the Secret API Key only on servers and choose the flag environment explicitly in SDK configuration.
• Send stable opaque user IDs instead of raw personally identifiable information.
• Keep a safe fallback path for unavailable flags or network failures.

API reference links

Environment variables

Add the following variable to your .env.local file:

FLAGPILOT_SECRET_KEY=fk_secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Find your Secret API Key in Dashboard → Settings → Keys & Authentication.

Streaming evaluations

For Next.js App Router or Remix streaming routes, use the async evaluation pattern. The SDK is fully compatible with React Server Components and Server Actions:

import { FlagPilot } from '@flagpilot/node';

// app/page.tsx — React Server Component
export default async function Page() {
  const flagpilot = new FlagPilot({
    apiKey: process.env.FLAGPILOT_SECRET_KEY,
    environment: 'production'
  });

  const [newCheckout, betaDashboard] = await Promise.all([
    flagpilot.evaluate('checkout-v2', { userId: user.id }),
    flagpilot.evaluate('beta-dashboard', { userId: user.id }),
  ]);

  return (
    <>
      {newCheckout ? <NewCheckout /> : <LegacyCheckout />}
      {betaDashboard && <BetaBanner />}
    </>
  );
}

Version compatibility