navieo

Getting Started

Navieo adds AI-powered guided tours to your web application. Users ask questions in a chat widget and get step-by-step visual tours that highlight the right UI elements — no manual tour authoring needed.

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

Add NavieoProvider to your root layout:

import { NavieoProvider } from "@navieo/react";

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

A floating chat widget will appear in the bottom-right corner of your app.

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 SDK reads this automatically and sends it as an x-api-key header with each request.

3. Connect your GitHub repository

From the Navieo dashboard:

  1. Open your app
  2. Go to Integrations → GitHub
  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

On the Scan page in your dashboard, click Scan Codebase. Navieo reads your source code via the GitHub API and automatically:

  • Discovers all routes in your project
  • Extracts interactive elements (buttons, links, inputs, forms)
  • Maps CSS selectors for tour highlighting
  • Builds a knowledge base for the AI

The scan takes 5–30 seconds depending on project size.

5. Optional: Enrich with AI

Click Enrich with AI to generate semantic descriptions for your routes and elements. This improves tour quality by giving the AI richer context about what each page and element does.

6. Optional: SPA navigation

For frameworks with client-side routing (Next.js, React Router, etc.), use the Next.js convenience wrapper for smooth navigation:

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

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

Or pass your router's push function manually:

"use client";
import { NavieoProvider } from "@navieo/react";
import { useRouter } from "next/navigation";

export function Providers({ children }) {
  const router = useRouter();

  return (
    <NavieoProvider onNavigate={(route) => router.push(route)}>
      {children}
    </NavieoProvider>
  );
}

Uninstalling Navieo

1. Delete the app from the dashboard

Go to your Navieo dashboard, open the app, scroll to the Danger Zone, and click Delete App. This permanently removes all server-side data (sitemap, embeddings, analytics, API key).

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 a .navieo/ directory was created in your repo (from GitHub sync), delete it:

rm -rf .navieo/

4. Uninstall the package

npm uninstall @navieo/react

That's it. Navieo leaves no background processes, service workers, or global state behind.

What's Next

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