Skip to main content

Next.js SDK

Guided sample​

Open the Next.js sample. Begin with the README, then read lib/env.ts (public versus server settings), lib/toggly.ts (initialization), lib/order-context.ts (entity mapping), and the server/client/edge pages. Browser, Node server, and edge APIs are distinct—follow the matching runtime page.

A NEXT_PUBLIC_ value is shipped to the browser. Use only public App Keys there; keep management credentials out of browser configuration. Offline defaults and fixture tests do not establish live dashboard connectivity.

Use Toggly's feature flags in Next.js 14+ applications with full support for Server Components, Client Components, Server Actions, Middleware, and Edge Runtime.

Grab the printable Next.js cheat sheet (download PDF) — server components, client hooks, edge middleware, SSR hydration.

Architecture​

The Next.js SDK is modular with 4 packages:

PackageDescription
@ops-ai/nextjs-toggly-coreShared client, types, and local/remote evaluation
@ops-ai/nextjs-toggly-serverServer Components, Server Actions, Route Handlers
@ops-ai/nextjs-toggly-clientReact hooks and Client Components
@ops-ai/nextjs-toggly-edgeMiddleware and Edge Runtime support

Server packages evaluate flags in Node — pass user identity and entity context on each check. Client and edge packages load flags for the browser and middleware. When a flag depends on an entity (an order, a page, an account), evaluate it on the server and pass the result to the client.

Benefits​

  • Server Components render features without client JavaScript
  • Client Components get real-time updates with React hooks
  • Middleware enables feature-based routing at the edge
  • Full TypeScript support with strict types
  • SSR/SSG compatible with proper hydration
  • Supports both App Router and Pages Router patterns

Installation​

Install the packages you need:

# Install all packages (recommended)
npm install @ops-ai/nextjs-toggly-core @ops-ai/nextjs-toggly-server @ops-ai/nextjs-toggly-client @ops-ai/nextjs-toggly-edge

Or install individually based on your needs:

# Server Components only
npm install @ops-ai/nextjs-toggly-core @ops-ai/nextjs-toggly-server

# Client Components only
npm install @ops-ai/nextjs-toggly-core @ops-ai/nextjs-toggly-client

# Middleware only
npm install @ops-ai/nextjs-toggly-core @ops-ai/nextjs-toggly-edge

Quick Start​

Server Components​

app/dashboard/page.tsx
import { initServerToggly, Feature } from '@ops-ai/nextjs-toggly-server'

// Initialize in the root layout (process-wide singleton)
await initServerToggly({
  appKey: process.env.TOGGLY_APP_KEY!,
})

export default async function DashboardPage() {
  return (
    <Feature featureKey="new-dashboard">
      <NewDashboard />
    </Feature>
  )
}

Client Components​

app/providers.tsx
'use client'
import { TogglyProvider } from '@ops-ai/nextjs-toggly-client'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <TogglyProvider
      config={{
        appKey: process.env.NEXT_PUBLIC_TOGGLY_APP_KEY!,
        environment: 'Production',
      }}
    >
      {children}
    </TogglyProvider>
  )
}
components/feature-button.tsx
'use client'
import { useFeatureFlag } from '@ops-ai/nextjs-toggly-client'

export function FeatureButton() {
  const { isEnabled, isLoading } = useFeatureFlag('new-button')

  if (isLoading) return <LoadingSpinner />

  return isEnabled ? <NewButton /> : <OldButton />
}

Middleware​

middleware.ts
import { createFeatureMiddleware } from '@ops-ai/nextjs-toggly-edge'

const featureMiddleware = createFeatureMiddleware({
  appKey: process.env.TOGGLY_APP_KEY!,
})

export async function middleware(request: NextRequest) {
  return featureMiddleware(request, {
    featureKey: 'beta-access',
    redirectTo: '/waitlist',
  })
}

export const config = {
  matcher: '/beta/:path*',
}

Environment Variables​

.env.local
# Server-side (private)
TOGGLY_APP_KEY=your-app-key

# Client-side (public)
NEXT_PUBLIC_TOGGLY_APP_KEY=your-app-key

Features​

Server-Side​

  • Async Components: Feature, FeatureVariant (negate, context / contextKind)
  • Server Actions: checkFeature(), checkFeatureGate() (string identity or { identity, context, contextKind })
  • Local evaluation: identity and entity context are per-call, not a fetch query
  • Caching: Built-in caching with unstable_cache

Client-Side​

  • Hooks: useFeatureFlag(), useFeatureGate(), useFeatures()
  • Components: Feature, FeatureGate, FeatureSwitch
  • Context: TogglyProvider, useToggly()
  • Identity: Persist user identity for targeting

Edge Runtime​

  • Middleware: createFeatureMiddleware()
  • Path Matching: createPathFeatureMiddleware()
  • HOC: withFeatureGate()
  • Edge Caching: Cloudflare cache integration

Next Steps​