Skip to main content
This walkthrough starts from an empty Next.js app (App Router) and ends with a page that shows a flag and a config value and re-renders the moment either changes in the Nexus console. The last part adds the server side: a route handler that reads a secret through the Node.js SDK. A Vite variant is at the end. You need Node.js 20.19 or newer, and a frontend service in Nexus with a public key (wxp_...). For the server-side part, a backend service with a secret key (wxs_...) as well.

1. Create the app

2. Point npm at the registry and install

The packages are served from the GitLab package registry of the westyx/nexus/sdk group, which serves every @westyx-nexus package from one URL. Create .npmrc next to package.json (it holds no credentials - commit it):

3. Put the endpoint and the key in .env.local

In the Nexus console, open the frontend service: its endpoint is on the service page, and the public key is created under API keys. Next.js inlines NEXT_PUBLIC_ variables into the browser bundle at build time, which is fine here: the endpoint and a wxp_ key are public by design, and a public key never receives a secret.
.env.local

4. Wrap the app in NexusProvider

app/layout.tsx stays a Server Component. The SDK’s build is marked 'use client', so the provider renders as a client boundary without a wrapper file of your own.
app/layout.tsx
The provider runs the first sync before it renders children, so no component shows a default it would immediately replace; loadingFallback covers that moment. A server render produces loadingFallback only - the client is created in the browser.

5. Read a flag and a config

Hooks run in Client Components, so the page starts with 'use client':
app/page.tsx
useFlag returns false (or the second argument) for a flag the service does not define; useConfig returns undefined for a missing key, and its type parameter is a cast, not a check.

6. Run it

Open http://localhost:3000. The page shows the flag and the currency, and the badge reads Live once the update stream is connected. Toggle new.checkout in the console: the page re-renders within a second, without a reload.

When it does not work

Without onError, an initialisation failure is re-thrown to the nearest error boundary - for a provider in the root layout that is app/global-error.tsx. Pass onError={(err) => <p>{err.message}</p>} to the provider to render it in place instead.

The server side: secrets in a route handler

Secrets never reach a browser, so server code reads them with the Node.js SDK and a secret key of a backend service. Install it from the same registry:
.env.local
One client per server process. Keeping it on globalThis keeps a dev-mode reload from opening a second one, and server-only turns an accidental import from client code into a build error:
lib/nexus.ts
app/api/checkout/route.ts
await connection() marks the handler dynamic, so it runs per request rather than once at build time. The same nexus() works in a Server Component. The Node.js client keeps its own live stream, so the values it returns are as current as the browser’s.

Production

NEXT_PUBLIC_ values are fixed when next build runs, so set them in the build environment of each deployment. NEXUS_ENDPOINT and NEXUS_API_KEY are read at run time; set them on the server, never in a file that is committed.

Which API to use

Vite

With Vite the steps are the same up to the environment: the variables carry the VITE_ prefix in .env.local, and the provider wraps the app in src/main.tsx.
.env.local
src/main.tsx
App reads values with the same hooks as step 5, without the 'use client' line.

Next

Configuration

Every option, the deadlines, and local development without a key.

API reference

Every hook, the client, and the types.

Caching behaviour

When values refresh, and what happens when the server pushes back.

OpenFeature

The bridge provider and per-user targeting.