Use SwitchPilot with Next.js

Control product features from Next.js server code while keeping project API keys out of the browser.

Server-side essentials

Security and runtime requirements for every integration.

Official SDKs are server-side only.

Never expose API keys in browser or client code.

Store API keys in environment variables.

The default fallback is false.

SDKs fail safely if SwitchPilot is unreachable.

Default cache TTL: 60 seconds.

Default stale-if-error window: 5 minutes.

SwitchPilot is server-side only

Do not use NEXT_PUBLIC_SWITCHPILOT_API_KEY. SwitchPilot API keys must never be exposed in Client Components or browser code.

Install and configure

terminal

pnpm add @switchpilot/node

The SDK requires Node.js 18 or newer and must run on the server.

Use it in Server Components, Server Actions, Route Handlers, API routes, and backend services inside your Next.js app.

.env.local — correct

SWITCHPILOT_API_KEY="sp_live_your_project_key"

Never make the key public

Correct: SWITCHPILOT_API_KEY

Wrong: NEXT_PUBLIC_SWITCHPILOT_API_KEY

Next.js bundles NEXT_PUBLIC_ values into browser code. Never prefix the SwitchPilot API key with NEXT_PUBLIC_.

1. Create a server-only client

Keep one reusable client in a module protected byserver-only.

lib/switchpilot.ts

import "server-only";

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

export const switchpilot = createSwitchPilot({
  apiKey: process.env.SWITCHPILOT_API_KEY!,
});

2. Use it in a Server Component

app/page.tsx

import { switchpilot } from "@/lib/switchpilot";

export default async function Page() {
  const newDashboard = await switchpilot.isEnabled("new-dashboard");

  return (
    <main>
      {newDashboard ? "New dashboard" : "Old dashboard"}
    </main>
  );
}

This code runs server-side, where the API key remains private.
The flag value updates on the next render or request.
A page already open in the browser will not live-update automatically.

3. Route Handler usage

app/api/flags/route.ts

// app/api/flags/route.ts
import { NextResponse } from "next/server";
import { switchpilot } from "@/lib/switchpilot";

export async function GET() {
  const allFlags = await switchpilot.getAll();

  return NextResponse.json({ flags: allFlags });
}

The API key stays on the server.
The browser calls only the local route in your Next.js app.
Client Components can safely use this route to receive the boolean flag values they need.

Return only safe values

Route Handlers are public HTTP endpoints. Add your app's normal authentication and authorization when these flag values should only be visible to signed-in or authorized users.

4. Live UI updates with safe server-side polling

Put this Client Component in your app after creating the Route Handler above.

components/live-dashboard-flag.tsx

"use client";

import { useEffect, useState } from "react";

export function LiveDashboardFlag() {
  const [enabled, setEnabled] = useState(false);

  useEffect(() => {
    async function loadFlag() {
      const response = await fetch("/api/flags", {
        cache: "no-store",
      });

      const data = await response.json();

      setEnabled(Boolean(data.flags["new-dashboard"]));
    }

    loadFlag();

    const interval = window.setInterval(loadFlag, 60_000);

    return () => window.clearInterval(interval);
  }, []);

  return (
    <div>
      {enabled ? "New dashboard" : "Old dashboard"}
    </div>
  );
}

The browser never talks directly to SwitchPilot.
The browser never receives the SwitchPilot API key.
This example polls its own server route every 60 seconds.
Use manual refresh only when the product genuinely needs it.
For most backend use cases, simple server-side SDK usage is enough.

Cache and fallback behavior

@switchpilot/node caches successful flag responses for 60 seconds by default. Change the duration with cacheTtlMs. Evaluations are local while fresh. If synchronization fails, the SDK uses Last Known Good for five additional minutes by default, then the configured fallback. The default fallback isfalse.