Next.js SDK

1Installation#

# 1. .npmrc in your project root: @abrova packages come from Abrova Center
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/

# 2. Install
npm install @abrova/flags-nextjs
# or
yarn add @abrova/flags-nextjs

2Two entry points#

The package root (@abrova/flags-nextjs) is the same as /client. The server SDK is only in /server, so it cannot end up in a browser bundle, and it refuses to start in a browser.

3Server-Side (App Router)#

Create one instance per process, in its own module:

// lib/flags.ts
import { AbrovaFlags } from '@abrova/flags-nextjs/server';

export const flags = new AbrovaFlags({
  apiKey: process.env.ABROVA_FLAGS_API_KEY!,
  serverSecret: process.env.ABROVA_FLAGS_SERVER_SECRET!,
  environment: 'production', // leave out to use the Default values
});

// app/page.tsx (Server Component)
import { flags } from '@/lib/flags';

export default async function Page() {
  await flags.init(); // the first call downloads the rules, later calls return at once

  const user = { userId: 'user-123', attributes: { plan: 'pro', country: 'IR' } };

  const newCheckout = flags.isEnabled('new-checkout', user);
  const theme = flags.getString('theme', user, 'light');

  return (
    <main data-theme={theme}>
      {newCheckout ? <NewCheckout /> : <OldCheckout />}
    </main>
  );
}

The context is passed with every call: userId, anonymousId and attributes, all optional. Percentage rollouts and variant splits use userId, or anonymousId when there is no user id.

The server entry behaves like the Node.js SDK: the same options (pollIntervalSeconds, initTimeoutMs, sendUsage, debug, logger), the same reasons and the same error handling. It also runs in the Edge runtime.

4Client-Side (React Hook)#

// app/providers.tsx
'use client';

import { AbrovaFlagsProvider } from '@abrova/flags-nextjs/client';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AbrovaFlagsProvider config={{
      apiKey: process.env.NEXT_PUBLIC_ABROVA_FLAGS_API_KEY!,
      environment: 'production', // leave out to use the Default values
    }}>
      {children}
    </AbrovaFlagsProvider>
  );
}

Using the Hook

// components/Checkout.tsx
'use client';

import { useEffect } from 'react';
import { useAbrovaFlags } from '@abrova/flags-nextjs/client';

export function Checkout({ userId, plan }: { userId: string | null; plan: string }) {
  const { isReady, isEnabled, getString, identify } = useAbrovaFlags();

  useEffect(() => {
    identify(userId, { plan }); // null means signed out
  }, [identify, userId, plan]);

  if (!isReady) return <Skeleton />;

  return isEnabled('new-checkout')
    ? <NewCheckout theme={getString('theme', 'light')} />
    : <OldCheckout />;
}

The hook returns client, isReady, the getters (isEnabled, getBoolean, getString, getNumber, getJson, getDetail, getAll) and the actions (identify, setUserId, setAttributes, reset, resetAnonymousId, refresh). The functions keep the same identity between renders, so they are safe in effect dependency lists. Components re-render when the values change.

Call identify in an effect, not in the component body.

5Standalone Client (No React)#

For browser code outside React, use AbrovaFlagsClient directly.

import { AbrovaFlagsClient } from '@abrova/flags-nextjs/client';

const client = new AbrovaFlagsClient({
  apiKey: 'ab_live_xxx',
  environment: 'production',
  userId: 'user-123',
  attributes: { plan: 'pro' },
});

await client.init();

const enabled = client.isEnabled('new-checkout');
const theme = client.getString('theme', 'light');
const detail = client.getDetail('theme', 'light', 'string');
// { key, value, enabled, variant, reason, version, valueType }

// Sign-out: clears the user, the attributes and the cached values
await client.reset();

// Stop timers and network work
client.close();

6How the client behaves#

• Context changes fetch new values after a short pause (250 ms). A call that changes nothing sends no request. setAttributes and the attributes of identify replace the whole set; they do not merge.
• User change: the previous user's values are dropped at once. Until the new values arrive, isReady is false and getters return your defaults.
• Anonymous id: each browser gets a random id (a UUID), kept in localStorage and sent with every request, so percentage rollouts work for signed-out visitors too. If storage is blocked, the id lives in memory for the page.
• Cache: the last values are kept in localStorage and served at the next visit, before the network answers. Offline or on errors, the last values keep being served.
• Refresh: on init, on context changes, when the tab becomes visible and the last fetch is older than 15 minutes, and on refresh(). Polling is off unless you set refreshIntervalSeconds (minimum 60).
• Errors: rate limits (429) and server errors are retried with a growing delay (up to 5 minutes). 401, 403 and 404 (wrong key, Flags not enabled, unknown environment) stop automatic fetches until refresh().
• Attributes are strings, numbers, booleans, null, or arrays of those. No nested objects. At most 100 attributes; a string holds at most 1,024 characters.

Client options: apiKey, environment, userId, attributes, flagKeys, refreshIntervalSeconds, initTimeoutMs, storage, debug and logger.

7Server rendering and hydration#

The client entry has no values while a page is rendered on the server: isReady is false and every getter returns the default you pass. In the browser, cached values from an earlier visit are available from the first render. The HTML from the server and the first render in the browser can therefore differ.

'use client';

import { useEffect, useState } from 'react';
import { useAbrovaFlags } from '@abrova/flags-nextjs/client';

export function PromoBanner() {
  const { isReady, isEnabled } = useAbrovaFlags();
  const [mounted, setMounted] = useState(false);

  useEffect(() => setMounted(true), []);

  if (!mounted || !isReady) return null;
  return isEnabled('promo-banner') ? <Banner /> : null;
}

8Environment Variables#

# .env.local

# Server-side only (NEVER expose these to the client)
ABROVA_FLAGS_API_KEY=ab_live_xxx
ABROVA_FLAGS_SERVER_SECRET=ab_srv_xxx

# For client-side usage (safe to expose)
NEXT_PUBLIC_ABROVA_FLAGS_API_KEY=ab_live_xxx
# Note: Do NOT create NEXT_PUBLIC_ABROVA_FLAGS_SERVER_SECRET

Upgrading from 0.1.x#

Update the package and change these imports and calls:

• Upgrade browser and server together: in 0.2.0 Abrova Flags evaluates for the browser, and a 0.1.x client entry stops receiving flags.
• The root import no longer exports the server SDK. Importing AbrovaFlags from @abrova/flags-nextjs no longer works: change it to @abrova/flags-nextjs/server.
• On the server, rename userAttributes to attributes. A context that still uses userAttributes is evaluated without attributes.
• Rollouts use a new bucketing method, so users are assigned to rollouts and variants again once.

Best Practices#