Guide

This guide builds on the SDK quickstart and shows you how to:

Create a new feature flag
Access it in your code
Configure targeting rules

Prerequisites

Set up Hypertune

1. Create a feature flag

Go to the Flags view in the dashboard. Click the + button in the top-right of the sidebar and select Flag.

Enter a name and choose a type. Use Boolean for simple on/off flags.

Click Create. The new flag is disabled by default. Click Save in the top-right to save your changes.

2. Access the feature flag in your code

Regenerate the client after adding a new flag:

npx hypertune

yarn hypertune

pnpm hypertune

Then use the generated method to access your feature flag:

Use the generated useHypertune hook:

components/ClientComponent.tsx

'use client'

import { useHypertune } from '@/generated/hypertune.react'

export default function ClientComponent() {
  const hypertune = useHypertune()

  const anotherFlag = hypertune.anotherFlag({ fallback: false })

  return <div>Another Flag: {String(anotherFlag)}</div>
}

To use flags in Server Components, use the getHypertune function. Include the <HypertuneClientLogger> component in your component tree, passing it the paths of any flags you use via the flagPaths prop. This ensures that flag evaluations and experiment exposures are logged on the client (in the browser):

components/ServerComponent.tsx

import { HypertuneClientLogger } from '@/generated/hypertune.react'
import getHypertune from '@/lib/getHypertune'

export default async function ServerComponent() {
  const hypertune = await getHypertune()

  const anotherFlag = hypertune.anotherFlag({ fallback: false })

  return (
    <div>
      Another Flag: {String(anotherFlag)}
      <HypertuneClientLogger flagPaths={['anotherFlag']} />
    </div>
  )
}

By default, remote logging is disabled on Next.js servers because prefetching and caching of pages and layouts can cause logs for flag evaluations, experiment exposures, and analytics events to differ from actual user behaviour. To ensure accuracy, remote logging is enabled by default on the client (in the browser) only. This is why you need to include the <HypertuneClientLogger> component in your component tree.

To use flags in Route Handlers, use the getHypertune function:

app/api/route.ts

import { waitUntil } from '@vercel/functions'
import { NextResponse } from 'next/server'
import getHypertune from '@/lib/getHypertune'

export const runtime = 'edge'

export async function GET() {
  const hypertune = await getHypertune({ isRouteHandler: true })

  const anotherFlag = hypertune.anotherFlag({ fallback: false })

  waitUntil(hypertune.flushLogs())

  return NextResponse.json({ anotherFlag })
}

Notes

Enable remote logging: By default, remote logging is disabled on Next.js servers because prefetching and caching of pages and layouts can cause logs for flag evaluations, experiment exposures, and analytics events to differ from actual user behaviour. To ensure accuracy, remote logging is enabled by default on the client (in the browser) only. However, since Route Handlers aren't subject to the same prefetching and caching patterns, remote logging is enabled for them by passing { isRouteHandler: true } in the call to getHypertune.
Flush logs: waitUntil(hypertune.flushLogs()) ensures that logs are sent. Without this, logs may still flush in the background, but this isn't guaranteed in serverless environments like Vercel deployments.

To use flags in Middleware, use the getHypertune function:

middleware.ts

import { NextRequest } from 'next/server'
import getHypertune from '@/lib/getHypertune'

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

export async function middleware(request: NextRequest) {
  const hypertune = await getHypertune()

  const anotherFlag = hypertune.anotherFlag({ fallback: false })

  console.log(`Another Flag: ${anotherFlag}`)
}

Include the <HypertuneClientLogger> component in your component tree, passing it the paths of any flags you use via the flagPaths prop. This ensures that flag evaluations and experiment exposures are logged on the client (in the browser):

app/page.tsx

import React from 'react'
import { HypertuneClientLogger } from '@/generated/hypertune.react'

export default async function Home() {
  return (
    <div>
      <h1>Home</h1>
      <HypertuneClientLogger flagPaths={['anotherFlag']} />
    </div>
  )
}