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
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.

Access the feature flag in your code
Regenerate the client after adding a new flag:
npx hypertuneyarn hypertunepnpm hypertuneThen use the generated method to access your feature flag:
Use the generated useHypertune hook:
'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):
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:
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 togetHypertune.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:
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):
import React from 'react'
import { HypertuneClientLogger } from '@/generated/hypertune.react'
export default async function Home() {
return (
<div>
<h1>Home</h1>
<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.
Once you deploy your code, you can remotely configure your flag at runtime.
Configure the feature flag's targeting rules
By default, a new flag is disabled. Click the toggle to enable it for everyone or add rules to enable it under certain conditions.
Enable for development
To enable the flag during development, click + Rule:

Choose Context > Environment. Select is one of and add Development. Click Save.

Enable for specific users
Click + Rule. Choose Context > User > Id. Select is one of and add user IDs. Click Save.

Next steps
Create variables to reuse logic across different flags, e.g. user segments.
Create an experiment to A/B test your feature or progressively roll it out.
Once the feature is fully rolled out, deprecate your flag.
Last updated