Skip to main content

Next.js Quickstart

Add Xaiku to your Next.js app with server-side variant fetching and middleware.

Prerequisites​

  • Next.js 16 (App Router)
  • A Xaiku account with a public key (pk_*)
  • A experiment created in the Xaiku dashboard

1. Install​

npm install @xaiku/nextjs

2. Set your environment variable​

.env.local
NEXT_PUBLIC_XAIKU_API_KEY=pk_your_public_key

3. Add the middleware​

The middleware manages a GUID cookie for consistent variant assignment.

middleware.js
import { xaikuMiddleware } from '@xaiku/nextjs/server'

export async function middleware(request) {
  return xaikuMiddleware(request)
}

4. Add the Provider​

Use the server-side provider in your root layout. It fetches experiment variants on the server and hydrates the client.

app/layout.js
import { XaikuProvider } from '@xaiku/nextjs/server'

export default async function RootLayout({ children }) {
  return (
    <html>
      <body>
        <XaikuProvider>{children}</XaikuProvider>
      </body>
    </html>
  )
}

5. Display variant text​

Use the same components as @xaiku/react — they're re-exported from @xaiku/nextjs:

app/page.js
import { Experiment, Text } from '@xaiku/nextjs'

export default function Page() {
  return (
    <Experiment id="your_experiment_id">
      <Text id="headline" fallback="Welcome">
        {(text) => <h1>{text}</h1>}
      </Text>
    </Experiment>
  )
}

How it works​

@xaiku/nextjs has two entry points:

ImportEnvironmentWhat it does
@xaiku/nextjsClientRe-exports all @xaiku/react components + Next.js SDK factory
@xaiku/nextjs/serverServerServer-side provider, middleware, and SDK factory using @xaiku/node

The server provider fetches variants at request time and passes them to the client provider, avoiding a client-side fetch waterfall.

Next steps​