navieo

Getting Started

Navieo helps users learn your application through answers and guided walkthroughs. Start with a saved authored tour; assistant questions and live guidance are supported in React SDK 3.0.0. Check release compatibility before integrating.

Prerequisites

  • React 18 or 19 application
  • A Navieo account — sign up at navieo.io/dashboard to get your API key
  • Your app's code in a GitHub repository

Installation

Install the Navieo React SDK:

npm install @navieo/react

Or with your preferred package manager:

pnpm add @navieo/react

Quick Setup

1. Wrap your app

For Next.js App Router, create a client-side provider and mount it once inside your root layout:

"use client";
import type { ReactNode } from "react";
import { NavieoNextProvider } from "@navieo/react/next";

export function Providers({ children }: { children: ReactNode }) {
  return (
    <NavieoNextProvider>
      {children}
    </NavieoNextProvider>
  );
}

A floating widget appears when configuration permits it. For another React SPA, use the generic provider with that router's navigation callback; see the example below.

Current release: React 3.0.0 includes compatible Core 2.0.0 and Types 3.0.0 dependencies for assistant questions, live guidance and authored tours. See API & Authentication. Use the SDK rather than calling backend assistant routes directly.

2. Set your API key

Add your publishable key (from the dashboard) to your environment:

NEXT_PUBLIC_NAVIEO_PUBLISHABLE_KEY=nv_pub_your_key_here

The Next.js build exposes this to the SDK, which sends it as x-api-key. Other bundlers should pass publishableKey explicitly through their own public environment mechanism. Never use a secret key in browser code.

3. Connect your GitHub repository

From the Navieo dashboard:

  1. Open your app
  2. Go to Codebase → Connect
  3. Click Connect Repository
  4. Authorize Navieo for your GitHub organization
  5. Select your repository

Once connected, your repo name appears with a green "Connected" badge.

4. Scan your codebase

Open Codebase → Scan and click Scan Codebase. Navieo reads your source code via the GitHub API and automatically:

  • Discovers statically supported routes in your project
  • Extracts interactive elements (buttons, links, inputs, forms)
  • Derives bounded selector and navigation evidence
  • Builds a knowledge base for the AI

The dashboard shows progress while the scan runs; duration varies with repository size and provider latency.

5. Optional: Enrich with AI

Click Enrich with AI only after reviewing its data boundary: the current repository enrichment path sends route metadata and source excerpts to the configured provider. It can add retrieval context but does not create executable selectors or navigation edges. It is optional, can be wrong, and is not required for live guidance.

6. Optional: framework-aware routing

Use NavieoNextProvider for Next.js App Router, not a generic provider with only a push callback:

"use client";
import { NavieoNextProvider } from "@navieo/react/next";

export default function Layout({ children }) {
  return (
    <NavieoNextProvider>
      {children}
    </NavieoNextProvider>
  );
}

For a React Router application, mount this inside the router:

"use client";
import { NavieoProvider } from "@navieo/react";
import { useNavigate } from "react-router-dom";

export function Providers({ children }) {
  const navigate = useNavigate();

  return (
    <NavieoProvider onNavigate={(route) => navigate(route)}>
      {children}
    </NavieoProvider>
  );
}

Verify an authored tour

Create and activate a tour in the dashboard, then launch it with playTour(slug) or a suggestion whose tourSlug matches the saved tour. This checks authored-tour playback separately from assistant guidance.

With a compatible guidance release, ask a question from your application, accept Take me there when offered, and follow the highlighted controls to the intended destination and finish any remaining guidance. The dashboard's Test Query preview does not launch guidance on your application. Read Live Guidance & Privacy for configuration and privacy options.

Uninstalling Navieo

1. Delete the app from the dashboard

Go to your Navieo dashboard, open the app's Settings → General → Danger Zone, and select Delete App. This permanently removes the app and associated data. Uninstalling the SDK alone does not require deleting the app.

2. Remove the SDK from your code

Remove the NavieoProvider wrapper from your root layout and delete NEXT_PUBLIC_NAVIEO_PUBLISHABLE_KEY from your .env file.

3. Remove local Navieo files

If you no longer need .navieo/, review and archive any authored documentation or configuration before removing it through your normal version-control workflow.

4. Uninstall the package

npm uninstall @navieo/react

Remove any separate host-side launchers as well. Browser-local authored-tour visit/trigger records and server-side app records have separate lifecycles; removing the package is not a data-erasure operation.

What's Next

  1. GitHub Integration — How the GitHub connection works, scanning, enrichment, and PR sync
  2. Provider Setup — Supported integration props and the useNavieo hook
  3. Sitemap Configuration — Your app's route and element map
  4. Themes — Customize the widget's look and feel