Vue product tour: add one to Vue and Nuxt apps

By Hasan · November 5, 2026 · 5 min read

To add a product tour to a Vue app, install @justonecx/sdk and call init() in main.ts after app.mount(). In Nuxt, put the call in a plugin named plugins/justonecx.client.ts. The .client suffix keeps it out of server rendering. Pass trackRouteChanges: true so tours follow your router.

What do you need?

  • Your public key (starts with pk_) from Settings, Developers.
  • Your site's origin in Settings, Developers, Domains & CORS. For local work add your dev origin, for example http://localhost:3000.
  • The package: npm install @justonecx/sdk. If you prefer, use the script tag from the quickstart instead.

What rules apply in every framework?

  1. Call init() once, in the browser only, after the app mounts.
  2. In single-page apps, pass trackRouteChanges: true. The SDK then re-runs itself on each client-side navigation, so page targeting stays correct.
  3. Call identify() after sign-in and reset() on sign-out.

Use these options in the examples:

const options = {
  publicKey: "pk_your_workspace_key",
  apiUrl: "https://api.justonecx.com",
  trackRouteChanges: true,
};

How do you add it to a Vue app?

Call init in main.ts, after the app is mounted:

// Vue: main.ts, after app.mount()
import { init } from "@justonecx/sdk";
void init(options);

Vue Router changes the page without a reload. That is why trackRouteChanges: true matters. If your router already calls init() on its own, leave it off.

How do you add it to Nuxt?

Create a client-only plugin:

// Nuxt: plugins/justonecx.client.ts
// The ".client" suffix keeps it out of server rendering.
import { init } from "@justonecx/sdk";
export default defineNuxtPlugin(() => {
  void init(options);
});

Do not call init() on the server. It uses window and document. If you see errors during server-side rendering, the call is running there. Move it into the .client plugin or an onMounted hook.

How do you identify the user?

Call identify after sign-in so you can target by plan or role, and call reset on sign-out:

import { identify, reset } from "@justonecx/sdk";

async function onSignedIn(user: { id: string; plan: string }, userHash: string) {
  await identify(user.id, { plan: user.plan }, { userHash });
}

async function onSignedOut() {
  await reset();
}

userHash comes from your server. See identity verification and how to secure identify with a user hash. Run init() before identify(). If you call identify() first, the SDK logs identify() called before init().

How do you build the tour?

  1. In the dashboard open Tours and create a tour.
  2. On the Builder tab, add a step and pick the element it points at.
  3. On the Settings tab, set targeting.
  4. Set the tour to Published.

Open your app in a new window. The tour starts. Use Preview on your site to test a draft with the JustOneCX browser extension.

A tooltip highlights the element found by the step's selector. It can also find the element by visible text, an ARIA role with an accessible name, or a data-jcx anchor. Text and role targets keep working when generated class names change, which helps with scoped styles that rename classes.

If the element is not on the page yet, the SDK waits for it. The default wait is 5 seconds, and you can set up to 30 seconds per step. This helps with Vue components that render after data loads.

Why does the tour not change when the route changes?

Pass trackRouteChanges: true to init(). Without it, page targeting runs only on the first load.

Why is nothing showing?

Open the console and look for the [JustOneCX] prefix. Then check:

  • The tour is Published. Drafts are never sent.
  • The public key is correct and apiUrl is set.
  • Your origin is allowed.
  • The visitor has not already finished or dismissed the tour. Use a private window.
  • With a VITE_* variable for the key (read at build time), an empty value means the SDK is skipped. Rebuild after setting it.

See why a product tour is not showing and the troubleshooting guide. To compare with other frameworks, read the React product tour guide and the Next.js product tour guide. The full list of frameworks is on the frameworks page.

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.

A second copy of the SDK on the same page, for example a tag manager plus the npm package, logs one warning and stays inactive. That keeps tours and chat from appearing twice.

How do you keep the SDK off some pages?

Use the excludePaths option in init() when nothing from JustOneCX should show on a page, such as an admin area. * is one path segment and ** is any depth, for example ["/admin/**", "/preview"]. To turn off one kind of content, use disableTours, disableAnnouncements or disableSurveys. Staff can also use disableChat: true so they do not open chats in their own product.

What does the tour builder show you?

The builder has three tabs. Builder holds the steps. Settings holds targeting, the launcher, the A/B test, voice narration and version history. Results shows how people moved through the tour. Save as template, Brand Kit, Unpublish and Delete are in the menu next to Save.

Frequently asked questions

Why does the Nuxt plugin end in .client?

The suffix keeps the plugin out of server rendering, so init() runs only in the browser.

Where does init go in a plain Vue app?

In main.ts, after app.mount().

Do I need trackRouteChanges?

Yes in a single-page app, so the SDK checks page targeting again after each client-side navigation.

What do I call on sign-out?

Call reset(). It clears identity and starts a new anonymous visitor.

See how it works in the live demo.

See it working in 2 minutes

Try the live demo

Related