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 thewestyx/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
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
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
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 theVITE_ 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.
