r valid A/B testing.
Sweet Spot: Evaluate routing, SEO, and initial UI flags at the Edge/Server level using parallel async calls. Delegate interactive, real-time, or preference-based flags to Client Components. Maintain a single source of truth for user context to prevent variant leakage.
Core Solution
Next.js App Router supports four distinct evaluation locations. The architectural rule is simple: evaluate flags as early as possible. Page-level flags belong on the server/edge; interactive flags belong on the client.
Architecture: Where to Evaluate Flags
| Location | SDK | Runs On | Best For |
|---|
| Server Components | @rollgate/sdk-node | Server (Node.js) | Initial render, SEO content, data-dependent flags |
| Client Components | @rollgate/sdk-react | Browser | Interactive UI, real-time updates, user preferences |
| Middleware | @rollgate/sdk-node | Edge/Node | A/B testing pages, redirects, geo-targeting |
| API Routes | @rollgate/sdk-node | Server (Node.js) | Backend logic, rate limits, feature-gated endpoints |
Server-Side Feature Flags
Server Components are async by default, making them ideal for flag evaluation. Fetching the flag value during rendering delivers correct HTML immediately.
Setup
Install the Node.js SDK:
npm install @rollgate/sdk-node
Create a shared Rollgate client that you can import anywhere on the server:
// lib/rollgate.ts
import { RollgateClient } from '@rollgate/sdk-node';
export const rollgate = new RollgateClient({
apiKey: process.env.ROLLGATE_SERVER_KEY!,
baseUrl: 'https://api.rollgate.io',
});
Using Flags in Server Components
// app/dashboard/page.tsx
import { rollgate } from '@/lib/rollgate';
import { getCurrentUser } from '@/lib/auth';
export default async function DashboardPage() {
const user = await getCurrentUser();
const showNewDashboard = await rollgate.isEnabled('new-dashboard', {
userId: user.id,
attributes: {
plan: user.plan,
email: user.email,
createdAt: user.createdAt,
},
});
if (showNewDashboard) {
return <NewDashboard user={user} />;
}
return <LegacyDashboard user={user} />;
}
Server Components with Multiple Flags
Evaluate multiple flags in parallel to avoid sequential waterfalls:
// app/settings/page.tsx
import { rollgate } from '@/lib/rollgate';
import { getCurrentUser } from '@/lib/auth';
export default async function SettingsPage() {
const user = await getCurrentUser();
const context = {
userId: user.id,
attributes: { plan: user.plan },
};
const [showBilling, showTeamSettings, showApiKeys] = await Promise.all([
rollgate.isEnabled('settings-billing-v2', context),
rollgate.isEnabled('team-management', context),
rollgate.isEnabled('api-keys-section', context),
]);
return (
<div>
<ProfileSettings />
{showBilling && <BillingV2 />}
{showTeamSettings && <TeamSettings />}
{showApiKeys && <ApiKeysSection />}
</div>
);
}
Client-Side Feature Flags
Interactive components (modals, tooltips, dynamic forms) live in Client Components. The React SDK provides a context provider and hooks for real-time updates.
Setup
Install the React SDK:
npm install @rollgate/sdk-react
Add the RollgateProvider in your root layout. Since providers require 'use client', create a wrapper component:
// components/providers.tsx
'use client';
import { RollgateProvider } from '@rollgate/sdk-react';
export function Providers({ children }: { children: React.ReactNode }) {
return (
<RollgateProvider
apiKey={process.env.NEXT_PUBLIC_ROLLGATE_CLIENT_KEY!}
baseUrl="https://api.rollgate.io"
>
{children}
</RollgateProvider>
);
}
// app/layout.tsx
import { Providers } from '@/components/providers';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}
Using Flags in Client Components
// components/feedback-widget.tsx
'use client';
import { useFlag } from '@rollgate/sdk-react';
export function FeedbackWidget() {
const showFeedback = useFlag('feedback-widget');
if (!showFeedback) return null;
return (
<div className="fixed bottom-4 right-4">
<button className="rounded-full bg-blue-600 p-3 text-white shadow-lg">
💬 Feedback
</button>
</div>
);
}
User Context on the Client
Pass user context to the provider to enable client-side targeting:
// components/providers.tsx
'use client';
import { RollgateProvider } from '@rollgate/sdk-react';
interface ProvidersProps {
children: React.ReactNode;
user?: {
id: string;
plan: string;
email: string;
};
}
export function Providers({ children, user }: ProvidersProps) {
return (
<RollgateProvider
apiKey={process.env.NEXT_PUBLIC_ROLLGATE_CLIENT_KEY!}
baseUrl="https://api.rollgate.io"
context={user ? {
userId: user.id,
attributes: { plan: user.plan, email: user.email },
} : undefined}
>
{children}
Pitfall Guide
- Late Evaluation & Hydration Mismatch: Evaluating page-level flags in Client Components causes FOUC and hydration errors. Always resolve initial UI flags in Server Components or Edge Middleware before HTML generation.
- Sequential Flag Waterfalls: Chaining multiple
await rollgate.isEnabled() calls serially blocks the React render tree. Always wrap concurrent flag checks in Promise.all() to parallelize network requests.
- Context Desynchronization: Passing mismatched
userId or attributes between server and client environments causes variant leakage and corrupts analytics. Propagate a single, deterministic context object across all evaluation layers.
- Exposing Server Keys: Accidentally importing
ROLLGATE_SERVER_KEY into 'use client' components or the browser SDK compromises security and enables unauthorized flag manipulation. Strictly separate server (ROLLGATE_SERVER_KEY) and client (NEXT_PUBLIC_ROLLGATE_CLIENT_KEY) environment variables.
- Missing Fallback & Degradation Paths: Network timeouts, SDK initialization failures, or edge runtime limits can throw unhandled promises. Always implement default values or graceful UI fallbacks when flag evaluation fails.
- Ignoring Edge Runtime Constraints: Edge Middleware runs in a V8 isolate without Node.js APIs (fs, net, crypto). Using Node-specific SDKs or making backend DB calls in middleware will throw
ReferenceError. Restrict middleware flags to lightweight, CDN-cached evaluations.
- Over-Flagging Initial Render: Loading 10+ flags on every page visit increases payload size and evaluation latency. Group related flags into a single
getFlags() call or cache flag states in React Context/SWR to minimize redundant network calls.
Deliverables
- 📐 Blueprint: Next.js Feature Flag Architecture
Visual flow diagram mapping flag evaluation across Edge → Server → Client layers, including context propagation strategies, cache invalidation patterns, and hydration-safe rendering paths.
- ✅ Implementation & Security Checklist
12-point audit covering key separation, parallel evaluation patterns, hydration mismatch prevention, edge compatibility, fallback handling, and A/B test cohort consistency.
- ⚙️ Configuration Templates
Production-ready .env.example structure, rollgate.ts singleton client setup, providers.tsx context wrapper, and Promise.all() parallel evaluation snippet for quick scaffolding.
