FlagPilot

Use the Next.js SDK to initialize FlagPilot, evaluate flags, pass target users, and handle fallback behavior in production.

Installation

Terminal

npm install @flagpilot/next

Initialization

app/layout.tsx

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

// In Next.js Server Components / Middleware
export async function Page() {
  const flagpilot = new FlagPilot({
    apiKey: process.env.FLAGPILOT_SECRET_KEY,
    environment: 'production'
  });

  await flagpilot.initialize();

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

  return isEnabled ? <NewCheckout /> : <LegacyCheckout />;
}

Evaluating a flag

app/layout.tsx

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

Target users

Send stable opaque user IDs and optional attributes to keep percentage rollouts and targeting rules consistent.

app/layout.tsx

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

Error handling

Use a conservative fallback value when evaluation fails or the SDK cannot reach its configured source.

Best practices

Reuse one SDK client instance per app runtime.
Set the SDK environment option to development, staging, or production.
Hash or pseudonymize sensitive user identifiers before sending them to evaluations.

API reference links

SDK integration guide REST API reference Target users SDK health telemetry

FAQ

How does Next.js SDK interact with local caches?

Configurations are synced down using Edge Config or fallback REST triggers. The client automatically reads evaluations in-memory, resulting in sub-millisecond local evaluation times.

Where can I obtain support for Next.js SDK?

You can open a support ticket in your dashboard, check the community roadmap, or consult the FlagPilot Platform Status page.