@apex-inc/next

Next.js helper so the first HTML is already the visitor's experiment arm.

npm install @apex-inc/next @apex-inc/react

What you drop in

1. Middleware — mint or keep the apex_vid cookie on HTML pages.
2. assignExperiments(ids) — ask Apex which arm this visitor gets (same rules as GET /api/experiments/{id}/assign).
3. <ApexProvider assignments={…}> — from @apex-inc/react. useApexVariant(id) first-paints that arm.

// middleware.ts
import { apexVisitorMiddleware } from "@apex-inc/next";
import type { NextRequest } from "next/server";

export function middleware(request: NextRequest) {
  return apexVisitorMiddleware(request);
}

// app/page.tsx (server)
import { assignExperiments } from "@apex-inc/next";
import { ApexProvider } from "@apex-inc/react";
import { cookies, headers } from "next/headers";

const cookieStore = await cookies();
const headerStore = await headers();
const { assignments } = await assignExperiments(["exp_123"], {
  cookie: cookieStore.toString(),
  host: headerStore.get("host") ?? "",
  workspaceKey: process.env.NEXT_PUBLIC_APEX_WORKSPACE_KEY,
  apiBase: "https://app.apex.inc",
});

<ApexProvider assignments={assignments} search={search}>
  {children}
</ApexProvider>

Same-origin is the default (apiBase empty). Set apiBase and workspaceKey when Apex is on another host. Forward the request cookies (credentials / Cookie) and x-apex-workspace.

Pass { search } so ?_apex_preview= matches on first HTML.

Client-only apps

This helper cannot promise no flicker in a client-only SPA. There is no document request to assign on, so the first HTML cannot already be the assigned arm. Do not hide the page until /assign returns.

Snippet mode

Apex changing the DOM in the browser is a different path. Do not mix it with this helper.

Cookie

Name apex_vid, 365 days, path /, SameSite=lax. HTML documents only — not /api/* or static files.