feat(js): Next.js Pages Router support (#393)

Author: andreas-karlsson

Dockerfile

@@ -336,23 +336,26 @@ FROM openfeature-provider-js-base AS openfeature-provider-js.build
 
 RUN make build
 
-# Verify no bundle splitting occurred
+# Verify no bundle splitting occurred. rolldown's default chunkFileNames is
+# `[name]-[hash].js` (8+ alphanumeric hash), so any .js whose basename ends in
+# `-<hash>.js` is an auto-split chunk. Entry outputs are dot-separated
+# (`index.inlined.js`) or path-nested (`pages-router/api.js`), so they don't
+# match this pattern.
 RUN set -e; \
     echo "Verifying no bundle splitting in JS artifacts..."; \
-    UNEXPECTED_FILES=$(find dist -name '*.js' ! -name 'index.node.js' ! -name 'index.inlined.js' ! -name 'index.fetch.js' ! -name 'server.js' ! -name 'client.js' | head -10); \
-    if [ -n "$UNEXPECTED_FILES" ]; then \
+    SPLIT_CHUNKS=$(find dist -type f -name '*.js' | grep -E -- '-[A-Za-z0-9]{8,}\.js$' || true); \
+    if [ -n "$SPLIT_CHUNKS" ]; then \
       echo ""; \
       echo "❌ ERROR: Bundle splitting detected!"; \
       echo ""; \
-      echo "Found unexpected JavaScript files in dist/:"; \
-      echo "$UNEXPECTED_FILES"; \
+      echo "Found auto-split chunks in dist/ (filenames matching <name>-<hash>.js):"; \
+      echo "$SPLIT_CHUNKS"; \
       echo ""; \
-      echo "Only expected entry point files should be present."; \
-      echo "Check tsdown.config.ts configuration to prevent code splitting."; \
+      echo "Each public entry should be a self-contained bundle. Check tsdown.config.ts."; \
       echo ""; \
       exit 1; \
     fi; \
-    echo "✅ No bundle splitting detected - only expected files present"
+    echo "✅ No bundle splitting detected"
 
 # ==============================================================================
 # Pack OpenFeature Provider (JS) - Create tarball for publishing

openfeature-provider/js/.prettierignore

@@ -7,3 +7,4 @@ coverage/*
 api/*
 CHANGELOG.md
 README.md
+CLAUDE.md

openfeature-provider/js/README-REACT.md

@@ -37,29 +37,32 @@ yarn add @spotify-confidence/openfeature-server-provider-local react
 
 ### 1. Set up the provider (server-side)
 
-Create a file to initialize the OpenFeature provider:
+Use Next.js's [`instrumentation.ts`](https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation) hook to register the provider once at server startup:
 
 ```ts
-// lib/confidence.ts
-import { OpenFeature } from '@openfeature/server-sdk';
-import { createConfidenceServerProvider } from '@spotify-confidence/openfeature-server-provider-local';
+// instrumentation.ts (at the project root, or in src/ if you use a src folder)
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== 'nodejs') return;
 
-const provider = createConfidenceServerProvider({
-  flagClientSecret: process.env.CONFIDENCE_FLAG_CLIENT_SECRET!,
-});
+  const { OpenFeature } = await import('@openfeature/server-sdk');
+  const { createConfidenceServerProvider } = await import('@spotify-confidence/openfeature-server-provider-local');
 
-// Initialize once at startup
-await OpenFeature.setProviderAndWait(provider);
+  const provider = createConfidenceServerProvider({
+    flagClientSecret: process.env.CONFIDENCE_FLAG_CLIENT_SECRET!,
+  });
+  await OpenFeature.setProviderAndWait(provider);
+}
 ```
 
+`register` runs once when a Next.js server instance boots and is awaited before requests are served. It does not run during `next build`, so it's safe to perform network setup here.
+
 ### 2. Wrap your app with ConfidenceProvider
 
 In your layout or page (Server Component):
 
 ```tsx
 // app/layout.tsx
 import { ConfidenceProvider } from '@spotify-confidence/openfeature-server-provider-local/react-server';
-import './lib/confidence'; // Initialize provider
 
 export default async function RootLayout({ children }: { children: React.ReactNode }) {
   // Get user context from session, cookies, etc.
@@ -387,6 +390,98 @@ export default async function Page() {
 }
 ```
 
+## Next.js Pages Router
+
+When using the Pages Router, three subexports under `./pages-router/*` cover the equivalent of the App Router integration above. The client hooks (`useFlag`, `useFlagDetails`) are the same — only the server plumbing differs.
+
+- **`pages-router/server`** — `withConfidence`, a `getServerSideProps` decorator that resolves the flag bundle for the request and merges it into `pageProps`.
+- **`pages-router/client`** — `<ConfidencePagesProvider>`, which reads the bundle from `pageProps` and exposes it to the `useFlag` / `useFlagDetails` hooks (re-used as-is from `react-client`).
+- **`pages-router/api`** — `applyHandler`, the `/api/confidence/apply` POST handler the client uses to log exposure when a flag is read.
+
+Provider registration is router-agnostic: use the same [`instrumentation.ts`](#1-set-up-the-provider-server-side) setup shown for the App Router.
+
+### 1. Resolve flags in `getServerSideProps`
+
+`withConfidence` wraps a single `getServerSideProps`-shaped function that does your data fetching **and** returns the evaluation context to use for flag resolution (and optionally a `flags` allow-list). The decorator resolves the bundle without firing exposure, seals the resolve token, and merges it into `pageProps.confidence`.
+
+```tsx
+// pages/index.tsx
+import { useFlag } from '@spotify-confidence/openfeature-server-provider-local/react-client';
+import { withConfidence } from '@spotify-confidence/openfeature-server-provider-local/pages-router/server';
+
+export const getServerSideProps = withConfidence(async ({ req }) => {
+  const visitorId = req.cookies.uid ?? 'anon';
+  const data = await fetchSomeData();
+  return {
+    props: { data },
+    context: { visitor_id: visitorId },
+    flags: ['my-feature'], // optional — defaults to all flags
+  };
+});
+
+export default function Home({ data }: { data: SomeData }) {
+  const enabled = useFlag('my-feature.enabled', false);
+  return enabled ? <Feature data={data} /> : null;
+}
+```
+
+Returning `{ redirect }` or `{ notFound }` short-circuits before flag resolution, just like a normal `getServerSideProps`. For pages without their own data fetching, the body collapses to a single return:
+
+```tsx
+export const getServerSideProps = withConfidence(async ({ req }) => ({
+  props: {},
+  context: { visitor_id: req.cookies.uid ?? 'anon' },
+}));
+```
+
+### 2. Wrap your tree with `<ConfidencePagesProvider>`
+
+Any component that calls `useFlag` / `useFlagDetails` must sit under a `<ConfidencePagesProvider>`. The simplest placement is `_app.tsx`, which covers every page in one spot — but the wrapper works anywhere in the tree, so per-page wrapping is also fine if you'd rather not touch `_app.tsx`.
+
+```tsx
+// pages/_app.tsx
+import type { AppProps } from 'next/app';
+import { ConfidencePagesProvider } from '@spotify-confidence/openfeature-server-provider-local/pages-router/client';
+
+export default function App({ Component, pageProps }: AppProps) {
+  const { confidence, ...rest } = pageProps;
+  return (
+    <ConfidencePagesProvider confidence={confidence}>
+      <Component {...rest} />
+    </ConfidencePagesProvider>
+  );
+}
+```
+
+Pages whose `getServerSideProps` doesn't use `withConfidence` simply have no `confidence` key on `pageProps`; the wrapper short-circuits and any `useFlag` calls in their tree fall back to default values.
+
+### 3. Mount the apply API route
+
+When a flag is read on the client (e.g. `useFlag` firing on mount), the wrapper POSTs `{ resolveToken, flagName }` to the apply route, which opens the sealed token and logs exposure server-side. Mount the handler at `/api/confidence/apply`:
+
+```ts
+// pages/api/confidence/apply.ts
+import { applyHandler } from '@spotify-confidence/openfeature-server-provider-local/pages-router/api';
+export default applyHandler();
+```
+
+If you need to mount it elsewhere, pass the same path to `<ConfidencePagesProvider apiPath="...">`.
+
+### Resolve token security
+
+In the App Router, the resolve token stays in the encrypted closure of a server action. The Pages Router has no equivalent, so the lib **seals the token with AES-256-GCM** before it ever reaches the browser. Set a server-only key:
+
+```bash
+CONFIDENCE_TOKEN_KEY=$(openssl rand -hex 32)
+```
+
+The client only ever sees the sealed value; the apply API route opens it server-side.
+
+### What's not in this integration
+
+- No equivalent to `getFlag` / `getFlagDetails` server functions — call `OpenFeature.getClient().getXxxValue(...)` directly inside `getServerSideProps` if you need eager-exposure server-only resolution.
+- No `getStaticProps` support: flag resolution is per-request and depends on evaluation context.
+
 ## Troubleshooting
 
 ### "ConfidenceProvider requires a ConfidenceServerProviderLocal"

openfeature-provider/js/package.json

@@ -32,6 +32,18 @@
       "types": "./dist/client.d.ts",
       "default": "./dist/client.js"
     },
+    "./pages-router/server": {
+      "types": "./dist/pages-router/server.d.ts",
+      "default": "./dist/pages-router/server.js"
+    },
+    "./pages-router/client": {
+      "types": "./dist/pages-router/client.d.ts",
+      "default": "./dist/pages-router/client.js"
+    },
+    "./pages-router/api": {
+      "types": "./dist/pages-router/api.d.ts",
+      "default": "./dist/pages-router/api.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -60,6 +72,7 @@
     "debug": "^4.4.3",
     "dotenv": "^17.2.2",
     "happy-dom": "^20.3.4",
+    "next": "^16.0.0",
     "prettier": "^2.8.8",
     "react": "^19",
     "react-dom": "^19.2.3",
@@ -72,6 +85,7 @@
   "peerDependencies": {
     "@openfeature/core": "^1.0.0",
     "debug": "^4.4.3",
+    "next": ">=13.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
@@ -81,6 +95,9 @@
     "debug": {
       "optional": true
     },
+    "next": {
+      "optional": true
+    },
     "react": {
       "optional": true
     }

openfeature-provider/js/src/pages-router/api.test.ts

@@ -0,0 +1,106 @@
+import { OpenFeature } from '@openfeature/server-sdk';
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { applyHandler } from './api';
+import { __resetKeyCacheForTests, sealResolveToken } from './token';
+
+function makeReqRes(
+  method: string,
+  body?: unknown,
+): { req: NextApiRequest; res: NextApiResponse; status: () => number } {
+  const headers: Record<string, string> = {};
+  let statusCode = 200;
+  const res = {
+    setHeader: vi.fn((k: string, v: string) => {
+      headers[k] = v;
+    }),
+    status: vi.fn((code: number) => {
+      statusCode = code;
+      return res;
+    }),
+    end: vi.fn(),
+  } as unknown as NextApiResponse;
+  const req = { method, body } as NextApiRequest;
+  return { req, res, status: () => statusCode };
+}
+
+describe('applyHandler', () => {
+  beforeAll(() => {
+    process.env.CONFIDENCE_TOKEN_KEY = 'test-key-do-not-use-in-prod';
+    __resetKeyCacheForTests();
+  });
+
+  afterEach(() => {
+    OpenFeature.clearProviders();
+  });
+
+  it('returns 405 for non-POST', async () => {
+    const handler = applyHandler();
+    const { req, res, status } = makeReqRes('GET');
+    await handler(req, res);
+    expect(status()).toBe(405);
+    expect(res.setHeader).toHaveBeenCalledWith('Allow', 'POST');
+  });
+
+  it('returns 400 when body is missing', async () => {
+    const handler = applyHandler();
+    const { req, res, status } = makeReqRes('POST');
+    await handler(req, res);
+    expect(status()).toBe(400);
+  });
+
+  it('returns 400 when fields have wrong types', async () => {
+    const handler = applyHandler();
+    const { req, res, status } = makeReqRes('POST', { resolveToken: 123, flagName: 'x' });
+    await handler(req, res);
+    expect(status()).toBe(400);
+  });
+
+  it('returns 503 when no Confidence provider is registered', async () => {
+    const handler = applyHandler();
+    const sealed = sealResolveToken('opaque');
+    const { req, res, status } = makeReqRes('POST', { resolveToken: sealed, flagName: 'my-flag' });
+    await handler(req, res);
+    expect(status()).toBe(503);
+  });
+
+  it('returns 400 when the resolveToken cannot be opened', async () => {
+    // Register a real-shaped provider so the 503 branch doesn't shortcut.
+    OpenFeature.setProvider({
+      metadata: { name: 'ConfidenceServerProviderLocal' },
+      applyFlag: vi.fn(),
+    } as never);
+    const handler = applyHandler();
+    const { req, res, status } = makeReqRes('POST', { resolveToken: 'not-a-real-handle', flagName: 'x' });
+    await handler(req, res);
+    expect(status()).toBe(400);
+  });
+
+  it('skips applyFlag and returns 204 when the opened token is empty (error bundle)', async () => {
+    const applyFlag = vi.fn();
+    OpenFeature.setProvider({
+      metadata: { name: 'ConfidenceServerProviderLocal' },
+      applyFlag,
+    } as never);
+    const sealed = sealResolveToken(''); // FlagBundle.error() ships resolveToken: ''
+    const handler = applyHandler();
+    const { req, res, status } = makeReqRes('POST', { resolveToken: sealed, flagName: 'my-flag' });
+    await handler(req, res);
+    expect(applyFlag).not.toHaveBeenCalled();
+    expect(status()).toBe(204);
+  });
+
+  it('calls applyFlag on success and returns 204', async () => {
+    const applyFlag = vi.fn();
+    OpenFeature.setProvider({
+      metadata: { name: 'ConfidenceServerProviderLocal' },
+      applyFlag,
+    } as never);
+    const sealed = sealResolveToken('the-real-token');
+    const handler = applyHandler();
+    const { req, res, status } = makeReqRes('POST', { resolveToken: sealed, flagName: 'my-flag' });
+    await handler(req, res);
+    expect(applyFlag).toHaveBeenCalledWith('the-real-token', 'my-flag');
+    expect(status()).toBe(204);
+  });
+});

openfeature-provider/js/src/pages-router/api.ts

@@ -0,0 +1,58 @@
+import type { NextApiHandler } from 'next';
+import { getConfidenceProvider } from './common';
+import { openResolveToken } from './token';
+
+export interface ApplyHandlerOptions {
+  /** Use a non-default OpenFeature provider by name. */
+  providerName?: string;
+}
+
+/**
+ * Builds the POST handler that the client `ConfidencePagesProvider` calls to
+ * fire exposure events. Mount it at `/api/confidence/apply` (or pass a custom
+ * `apiPath` to `ConfidencePagesProvider` if you mount it elsewhere).
+ *
+ * @example
+ * // pages/api/confidence/apply.ts
+ * import { applyHandler } from '@spotify-confidence/openfeature-server-provider-local/pages-router/api';
+ * export default applyHandler();
+ */
+export function applyHandler(opts: ApplyHandlerOptions = {}): NextApiHandler {
+  return async (req, res) => {
+    if (req.method !== 'POST') {
+      res.setHeader('Allow', 'POST');
+      res.status(405).end();
+      return;
+    }
+
+    const body = req.body as { resolveToken?: unknown; flagName?: unknown } | undefined;
+    if (!body || typeof body.resolveToken !== 'string' || typeof body.flagName !== 'string') {
+      res.status(400).end();
+      return;
+    }
+
+    const provider = getConfidenceProvider(opts.providerName);
+    if (!provider) {
+      res.status(503).end();
+      return;
+    }
+
+    let openedToken: string;
+    try {
+      openedToken = openResolveToken(body.resolveToken);
+    } catch {
+      res.status(400).end();
+      return;
+    }
+
+    // Error bundles carry an empty resolveToken (see FlagBundle.error); skip
+    // applyFlag in that case to match the App Router's `!bundle.errorCode` gate.
+    if (!openedToken) {
+      res.status(204).end();
+      return;
+    }
+
+    provider.applyFlag(openedToken, body.flagName);
+    res.status(204).end();
+  };
+}