Jake's pick

Nextstep Tours

Build product tours, onboarding flows, and interactive tutorials/lessons in Next.js with NextStep v2 (nextstepjs). Use when adding guided tours, walkthroughs, onboarding overlays, feature callouts, interactive lessons, or gated step-by-step tutorials to a Next.js App Router or Pages Router app. Covers NextStepProvider setup, multi-tour configuration, DOM-anchored and modal steps, multi-page tours with nextRoute/prevRoute, NextStepViewport for scrollable containers, custom card components, validation-gated progression, dark mode, analytics callbacks, and localization. Triggers: nextstep, nextstepjs, product tour, onboarding, walkthrough, guided tour, feature tour, tutorial overlay, interactive lesson, step-by-step guide, useNextStep, NextStepProvider, NextStepViewport, CardComponentProps.

Skill: nextstep-toursUse case: Web developmentSource: jakerains/AgentSkillsAdded: Jun 29, 2026

Install

npx skills add jakerains/AgentSkills --skill nextstep-tours

Install Options

Project installnpx skills add jakerains/AgentSkills --skill nextstep-tours

Global installnpx skills add jakerains/AgentSkills --skill nextstep-tours -g

Use oncenpx skills use jakerains/AgentSkills --skill nextstep-tours

Works With

codexclaude-codecursoropencode

Source

View source Open on skills.sh

Skill Preview

# NextStep Tours Skill

Build product tours, onboarding flows, and — most importantly — **interactive tutorials** with NextStep v2 (`nextstepjs`) in Next.js. This skill makes the action-gated lesson pattern the default rather than generic welcome popups.

## Quick Reference

| Task | Approach | Reference |
|------|----------|-----------|
| Install & wire provider | 3-step Quick Start | this file |
| Define a tour | `Tour` / `Step` schema | this file |
| Multi-page tour | `nextRoute` / `prevRoute` | references/multi-page-tours.md |
| Scrollable container | `NextStepViewport` | references/multi-page-tours.md |
| Custom card UI | `cardComponent` prop | references/custom-card.md |
| **Gate progress on user action** | **Custom card + validation registry** | **references/tutorial-authoring.md** |
| Full props & types | `NextStep` / `Step` / `CardComponentProps` | references/api-reference.md |
| Element not found, SSR, z-index | Troubleshooting table | references/troubleshooting.md |

**Core principle**: A tour that just shows tooltips teaches nothing. A tutorial that *requires the user to perform each action before advancing* teaches. Reach for the validation-gated pattern whenever the word "tutorial" or "lesson" appears.

---

## Install

```bash
npm i nextstepjs motion
# or: pnpm add nextstepjs motion / yarn add nextstepjs motion / bun add nextstepjs motion
```

`motion` is the peer dependency (the library formerly known as Framer Motion, used for step transitions).

**Pages Router users only**: if you hit ES module errors at runtime, see `references/troubleshooting.md` for the `next.config.js` fix.

---

## Minimal Working Example (App Router)

Three files. Drop-in ready.

### 1. `lib/tours.ts`

```ts
import type { Tour } from 'nextstepjs';

export const tours: Tour[] = [
  {
    tour: 'welcome',
    steps: [
      {
        icon: '👋',
        title: 'Welcome',
        content: "Let's take a quick look around.",
        selector: '#welcome-banner',
        side: 'bottom',
        showControls: true,
        showSkip: true,
        pointerPadding: 10,
        pointerRadius: 8,
      },
      {
        icon: '🧭',
        title: 'Navigation',
        content: 'Your main nav lives here.',
        selector: '#main-nav',
        side: 'right',
        showControls: true,
        showSkip: true,
      },
      {
        icon: '🎉',
        title: 'All set',
        content: "You're ready. Explore freely.",
        showControls: true,
      },
    ],
  },
];
```

### 2. `app/layout.tsx`

```tsx
import { NextStepProvider, NextStep } from 'nextstepjs';
import { tours } from '@/lib/tours';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <NextStepProvider>
          <NextStep steps={tours}>
            {children}
          </NextStep>
        </NextStepProvider>
      </body>
    </html>
  );
}
```

### 3. `components/start-tour-button.tsx` (client component that triggers the tour)

```tsx
'use client';
import { useNextStep } from 'nextstepjs';

export function StartTourButton() {
  const { startNextStep } = useNextStep();
  return <button onClick={() => startNextStep('welcome')}>Take a tour</button>;
}
```

Render `<StartTourButton />` anywhere inside the provider tree. Add `id="welcome-banner"` and `id="main-nav"` to the elements the steps target.

---

## The `Step` Shape

All props a single step supports — required ones first, optional below. Source of truth for every example in this skill.

```ts
type Step = {
  // ── Required ──────────────────────────────────────────────
  icon: React.ReactNode | string | null;  // emoji string, JSX, or null
  title: string;                           // step heading
  content: React.ReactNode;                // body (string or JSX)

  // ── Targeting ─────────────────────────────────────────────
  selector?: string;     // CSS #id of the element to anchor to. Omit for a centered modal step.
  side?: 'top' | 'bott

Tags

Install Options

Works With

Source

Skill Preview