To add a product tour to the Next.js App Router, create one client component that calls init() and identify(), then render it once in app/layout.tsx. The "use client" line keeps the SDK in the browser. You build and publish the tour in the dashboard, and the SDK plays it for matching visitors.
This works for any App Router app, including SaaS starters and paid boilerplates.
What do you need first?
- Your public key (starts with
pk_) from Settings, Developers. - Your origin in Settings, Developers, Domains & CORS, for example
https://app.example.com. For local work addhttp://localhost:3000. - The package:
npm install @justonecx/sdk.
How do you store the public key?
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_key
A NEXT_PUBLIC_* value is read at build time. If it is empty, the SDK is skipped and no request is made. Rebuild after you set it, and make sure your CI build sets it too.
How do you write the client component?
Create a 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 the option to check page targeting again after each change.
Where do you render it?
In app/layout.tsx, render <JustOneCX user={...} /> once. Get user from wherever your app reads the signed-in user on the server, such as 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 makes it run in the browser. Never call init() in server code. It uses window and document, and you will see errors during server-side rendering.
The longer walkthrough is in Add JustOneCX to a Next.js SaaS boilerplate.
How do you create the tour?
- In the dashboard open Tours and create a tour.
- On the Builder tab, add a step and pick the element it points at.
- On the Settings tab, set targeting.
- Set the tour to Published.
Open your app in a new browser window. The tour starts. For a draft, use Preview on your site, which uses the JustOneCX browser extension.
Tooltips can find an element by selector, visible text, an ARIA role with an accessible name, or a data-jcx anchor. In a framework that generates class names, text, role and anchor targets are the stable choice.
What about a tour that spans several pages?
Each step can have its own page rule, and the SDK saves where the visitor is. Because the App Router navigates in the browser, trackRouteChanges: true lets the SDK check again after each navigation and continue the tour. Read how a multi-page product tour works.
What should you do about identity verification?
Before you go live, turn on identity verification. Your server signs the user id with HMAC-SHA256, and the SDK sends userHash. The secret key stays in your server environment as JUSTONECX_SECRET_KEY and never reaches the browser. See secure identify with a user hash.
How do you debug a tour that does not show?
Open the console. The SDK logs every problem with the prefix [JustOneCX].
| You see | Fix |
|---|---|
| No request, no message | init() never ran, or the build had an empty NEXT_PUBLIC_* key. Rebuild. |
| CORS error or status 403 | Add the origin in Domains & CORS. |
| Status 401 | The public key is wrong or was rotated. Copy it again. |
| Nothing wrong in the console | The tour may be a draft, already seen, or targeted away from you. Test with Everyone targeting, in a private window. |
If targeted content does not appear right after sign-in, traits must be saved first. Run await identify(...), then call init() again.
See why a product tour is not showing and the troubleshooting page. For a plain React setup, see the React product tour guide.
What should you check before you ship?
- The tour is published and you saw it in a private window.
- Your production origin is in Domains & CORS, not only localhost.
- The build sets the public key, including your CI build.
- Sign-out calls
reset(), so a shared browser does not carry state over. - Identity verification is set up on your server before you go live.
The SDK also logs one warning and stays inactive if a second copy loads on the same page, for example a tag manager plus the npm package. That keeps tours from appearing twice.
Frequently asked questions
Does the component need to be a client component?
Yes. Use "use client", because init() must run in the browser only.
How many times should I render it?
Once, in the root layout.
What do I do on sign-out?
Call reset(). It clears identity and starts a new anonymous visitor, so the next person does not inherit the previous person's state.
Does it work in Remix?
Yes. React, Next.js, Remix and Preact share the same example in the docs.
See how it works in the live demo.