Feature Flags in Next.js: A Practical Production Guide

Keep evaluation on the server

A project API key is a secret. Evaluate flags in Server Components, Route Handlers, Server Actions, or your backend. Never expose the key through a public environment variable or client bundle.

Design the fallback before the happy path

Network calls fail. Choose the safest local behavior for each flag, keep the current experience as the default during migrations, and set timeouts appropriate to the request path.

import { createSwitchPilot } from "@switchpilot/node";

const flags = createSwitchPilot({
  apiKey: process.env.SWITCHPILOT_API_KEY!,
  fallback: { "new-dashboard": false },
});

export default async function Page() {
  const enabled = await flags.isEnabled("new-dashboard");
  return enabled ? <NewDashboard /> : <CurrentDashboard />;
}

Test both branches

A flag creates two production paths. Unit-test each branch, add an integration test around the boundary, and remove the old branch once rollout is complete. Flags should not become permanent accidental architecture.

Treat a toggle as an operational change

Before enabling Production, verify the environment, inspect known dependencies, check observability, and define a rollback state. A visual impact map adds context but cannot prove that a release is safe.