@arlioz/flagship-next

v5.1.0

Published

a month ago

Official Next.js SDK for FlagShip — SSR-ready feature flags

Downloads

262

0High
0Medium
0Low

amaurylapaque

feature-flags flagship next nextjs ssr react server-components

Install

npm install @arlioz/flagship-next @arlioz/flagship

@arlioz/flagship, react, and next are peer dependencies.

Quick Start (App Router)

1. Fetch flags server-side

// app/layout.tsx (Server Component)
import { getFlags } from '@arlioz/flagship-next/server'
import { Providers } from './providers'

export default async function RootLayout({ children }) {
  const flags = await getFlags({
    apiKey: process.env.FLAGSHIP_API_KEY!,
    baseUrl: process.env.FLAGSHIP_API_URL,
  })

  return (
    <html>
      <body>
        <Providers initialFlags={flags}>{children}</Providers>
      </body>
    </html>
  )
}

2. Wrap with provider

// app/providers.tsx
'use client'
import { FlagShipProvider } from '@arlioz/flagship-next'

export function Providers({ children, initialFlags }) {
  return (
    <FlagShipProvider
      apiKey={process.env.NEXT_PUBLIC_FLAGSHIP_API_KEY!}
      initialFlags={initialFlags}
    >
      {children}
    </FlagShipProvider>
  )
}

3. Use flags in components

'use client'
import { useFlag, Feature } from '@arlioz/flagship-next'

function MyComponent() {
  const darkMode = useFlag('dark-mode', false)

  return (
    <>
      {darkMode && <DarkTheme />}
      <Feature flag="beta" fallback={<ComingSoon />}>
        <BetaFeature />
      </Feature>
    </>
  )
}

4. Use flags in Server Components

import { getFlag } from '@arlioz/flagship-next/server'

export default async function Page() {
  const showBeta = await getFlag({ apiKey: process.env.FLAGSHIP_API_KEY! }, 'beta', false)
  return showBeta ? <BetaUI /> : <StableUI />
}

Two Entry Points

| Import | Use in | Description | | ------------------------------ | ----------------- | ---------------------------- | | @arlioz/flagship-next | Client Components | Provider, hooks, <Feature> | | @arlioz/flagship-next/server | Server Components | getFlags(), getFlag() |

API — Client

| Hook / Component | Return | Description | | ----------------------------------- | --------------------- | ------------------------- | | useFlag<T>(key, defaultValue?) | T | Single flag value | | useFlags() | Record<string, any> | All flags | | useFlagShipLoading() | boolean | True during initial fetch | | useFlagShipClient() | FlagShip | Client for imperative use | | <Feature flag children fallback?> | ReactNode | Conditional rendering |

API — Server

| Function | Return | Description | | --------------------------------- | ------------------------------ | -------------------------------- | | getFlags(options) | Promise<Record<string, any>> | Fetch all flags (auto-cleanup) | | getFlag(options, key, default?) | Promise<T> | Fetch single flag (auto-cleanup) | | FlagShipServer | class | Long-lived server client |

SSR Benefits

No hydration mismatch — initialFlags ensures server and client render identically
No flash of default content — flags are available on first render
Client-side polling — flags continue updating after hydration

Compatibility

Next.js >= 13.0.0 (App Router + Pages Router)
React >= 17.0.0

License

MIT — Arlioz