Add JustOneCX to a Next.js SaaS boilerplate
This guide is for any Next.js App Router app, including SaaS starters and paid boilerplates. It only uses what is true for every App Router app. It does not name files in a specific boilerplate, because those differ. You find two places in your own code: the root layout, and the place where your app knows who is signed in.
What you need
- Your public key (starts with
pk_) from Settings → Developers. - Your site's origin in Settings → Developers → Domains & CORS, for example
https://app.example.com. For local work addhttp://localhost:3000. See Allowed origins. - The npm package:
npm install @justonecx/sdk.
1. Add the public key to your environment
The public key is safe in the browser. In Next.js a variable that starts with NEXT_PUBLIC_ is sent to the browser:
# .env.local
NEXT_PUBLIC_JUSTONECX_PUBLIC_KEY=pk_your_workspace_key2. Add one client component
Create a client component that starts the SDK once and identifies the signed-in user:
// components/justonecx.tsx
"use client";
import { useEffect } from "react";
import { identify, init, reset } from "@justonecx/sdk";
type Props = { user?: { id: string; plan?: string; userHash?: string } };
export function JustOneCX({ user }: Props) {
useEffect(() => {
void init({
publicKey: process.env.NEXT_PUBLIC_JUSTONECX_PUBLIC_KEY!,
apiUrl: "https://api.justonecx.com",
trackRouteChanges: true,
});
}, []);
useEffect(() => {
if (user) void identify(user.id, { plan: user.plan }, { userHash: user.userHash });
else reset();
}, [user]);
return null;
}trackRouteChanges: true matters in an App Router app. Navigation between pages happens in the browser, and the SDK needs it to check page targeting again after each change.
3. Render it once in the root layout
In app/layout.tsx, render <JustOneCX user={...} /> once. Get user from wherever your app reads the signed-in user on the server (your auth helper or session call). Pass only what the component needs: the id, a trait such as the plan, and later the hash.
If your layout is a server component, that is fine. The "use client" line in the component file is what makes it run in the browser.
4. Check it works
Open your app in a new window. Open the browser console: the SDK logs every problem with a [JustOneCX] prefix. Create a tour in the dashboard and publish it. If nothing shows, use the troubleshooting page.
5. Sign the user id on the server (identity verification)
Your public key is in the page, so anyone can call identify("someone-else"). Identity verification stops that: your server signs the user id, and the SDK sends the signature.
Store the Secret key only in your server environment, never with a NEXT_PUBLIC_ prefix:
# .env.local (server only)
JUSTONECX_SECRET_KEY=Add the empty name to .env.example. Paste the real key into your hosting dashboard yourself. Do not give it to an AI assistant or put it in code.
Then compute the hash in the server code that already knows the user, for example in your layout or a server helper:
import { createHmac } from "node:crypto";
export function justonecxHash(userId: string) {
return createHmac("sha256", process.env.JUSTONECX_SECRET_KEY!)
.update(userId)
.digest("hex");
}Pass the result as userHash in the user prop. Sign exactly the same string you pass to identify().
Order matters. Deploy the hash first and check that sign-ins verify. Only then turn on Require identity verification in Settings → Developers. If you turn it on before your live site sends the hash, all existing users count as unverified.
6. Ask your AI assistant to do it
If your assistant is connected to the MCP server, ask it: "Add JustOneCX to this Next.js app." It adds the component and the layout change and can save a first tour as a draft. It never sees your Secret key. You set that yourself.
What next
- Product tours and targeting
- Frameworks for other stacks
- Server events to send events your server can vouch for