Recipe: gradual rollout in Next.js

Ship a feature to a slice of users and dial it up over time. You evaluate a flag on the server with the server SDK using an ssk_ key, and you control the percentage in the flag’s environment config with a weighted rollout. No redeploy needed to change the percentage.

Before you start

• A feature flag exists (for example new_checkout). See flags.
• You have a server SDK key ssk_live_…. Keep it server-only, never ship it to the browser.

1. Install and init the server client

   Install

   npm install @statskit/sdk

   lib/statskit.ts

   import { StatsKitServerClient } from "@statskit/sdk";
   
   export const statskit = new StatsKitServerClient({
     apiKey: process.env.VERSUCH_SERVER_KEY!, // ssk_live_…
   });

   Put the key in an env var, not in source. In Next.js an un-prefixed env var (VERSUCH_SERVER_KEY, not NEXT_PUBLIC_…) stays server-side.

2. Evaluate the flag on the server

   Evaluate against a stable unit, the signed-in user’s id. Because assignment is deterministic on that unit, a user stays on the same side of the rollout across requests.

   Server component

   app/checkout/page.tsx

   import { statskit } from "@/lib/statskit";
   import { NewCheckout } from "./new-checkout";
   import { LegacyCheckout } from "./legacy-checkout";
   import { getUser } from "@/lib/auth";
   
   export default async function CheckoutPage() {
     const user = await getUser();
     const useNew = await statskit.isEnabled("new_checkout", user.id);
   
     return useNew ? <NewCheckout /> : <LegacyCheckout />;
   }

   Route handler

   app/api/checkout/route.ts

   import { statskit } from "@/lib/statskit";
   import { getUser } from "@/lib/auth";
   
   export async function POST(req: Request) {
     const user = await getUser();
     const useNew = await statskit.isEnabled("new_checkout", user.id);
   
     return useNew ? handleNewCheckout(req) : handleLegacyCheckout(req);
   }

3. Set a weighted rollout in the env config

   In the flag’s environment config, set the rollout for new_checkout to a small slice, say 10%. This is a percentage rollout keyed on the same unit, so 10% of users get the flag on and stay on. See targeting.

   📸 Visual

   Placeholder, the flag’s environment config showing a weighted/percentage rollout slider set to 10% for new_checkout. Source: dashboard (auth).

4. Dial it up

   Watch your metrics, then raise the rollout percentage: 10% → 25% → 50% → 100%. Because the config lives in StatsKit, changing the percentage takes effect without redeploying your Next.js app. If something looks wrong, drop it back to 0%.

Tip

Evaluate against a stable unit (user id or account id), not a random per-request value, or a user would flip between old and new checkout on every request. The deterministic hash on a stable unit is what keeps them consistent.

Related

• Server-side flags, the server SDK and evaluation.
• Flag targeting, rollout percentages and rules.
• Track events server-side to measure the rollout’s impact.