Flowsterix

Guided tours and onboarding flows for React applications. State machine-based, fully typed, with built-in persistence.

Getting Started

1. Install the packages

npm install @flowsterix/core @flowsterix/react motion

2. Add UI components via shadcn

npx shadcn@latest add https://flowsterix.com/r/tour-hud.json

This installs everything: overlay, popover, controls, progress, and step content primitives.

3. Define your first flow

import { createFlow } from '@flowsterix/core'
import { StepContent, StepTitle, StepText } from '@/components/step-content'

export const onboardingFlow = createFlow({
  id: 'onboarding',
  version: { major: 1, minor: 0 },
  autoStart: true,
  steps: [
    {
      id: 'welcome',
      target: 'screen',
      advance: [{ type: 'manual' }],
      content: (
        <StepContent>
          <StepTitle>Welcome!</StepTitle>
          <StepText>Let us show you around.</StepText>
        </StepContent>
      ),
    },
    {
      id: 'feature',
      target: { selector: '[data-tour-target="main-feature"]' },
      advance: [{ type: 'event', event: 'click', on: 'target' }],
      content: (
        <StepContent>
          <StepTitle>Try this feature</StepTitle>
          <StepText>Click this button to continue.</StepText>
        </StepContent>
      ),
    },
  ],
})

4. Add to your app

import { TourProvider } from '@flowsterix/react'
import { TourHUD } from '@/components/tour-hud'
import { onboardingFlow } from './flows'

export function App({ children }) {
  return (
    <TourProvider flows={[onboardingFlow]} storageNamespace="my-app">
      <TourHUD />
      {children}
    </TourProvider>
  )
}

That's it. The target selector matches any element in your DOM.

---

Using with AI Assistants

Install the Flowsterix skill to help AI agents implement tours in your codebase:

npx skills kvngrf/flowsterix

The skill provides patterns for step definitions, advance rules, lifecycle hooks, router integration, and more. Works with Claude Code, Cursor, and other AI coding assistants.

---

DevTools

Debug and manage your flows during development:

import { DevToolsProvider } from '@flowsterix/react/devtools'

export function App({ children }) {
  return (
    <TourProvider flows={[onboardingFlow]} storageNamespace="my-app">
      <DevToolsProvider enabled={process.env.NODE_ENV === 'development'}>
        <TourHUD />
        {children}
      </DevToolsProvider>
    </TourProvider>
  )
}

Features:

• Steps Tab - Drag-and-drop reorder, jump to any step, track active state
• Flows Tab - View all registered flows, edit JSON state, delete flow storage
• Element Grabber - Click any element to copy its selector for step targets

---

Features

• Declarative flows - Define steps with targets, content, and progression rules
• 5 advance rule types - Manual, event, delay, route, predicate
• Lifecycle hooks - onEnter, onResume, onExit for UI synchronization
• Persistence - localStorage, API, or custom storage adapters
• Versioning - Semantic versions with migration support
• Router integration - TanStack Router, React Router, Next.js App/Pages
• Accessibility - Focus trapping, keyboard navigation, ARIA labels
• Analytics hooks - Event system for integrating with your tracking

Documentation

Guide	Description
DevTools	Debug flows, manage state, capture element selectors
Storage Adapters	Persist state to localStorage, API, or custom backends
Versioning	Handle flow updates and migrations
Accessibility	Focus management, ARIA, reduced motion
Routing & Async	Router adapters, route-based steps, async targeting

Shadcn Components

All UI components are available via the shadcn registry:

# Individual components
npx shadcn@latest add https://flowsterix.com/r/tour-provider.json
npx shadcn@latest add https://flowsterix.com/r/tour-overlay.json
npx shadcn@latest add https://flowsterix.com/r/tour-controls.json
npx shadcn@latest add https://flowsterix.com/r/tour-progress.json

# Complete HUD (recommended)
npx shadcn@latest add https://flowsterix.com/r/tour-hud.json

# Example flow
npx shadcn@latest add https://flowsterix.com/r/onboarding-flow.json

Examples

This repo includes example apps for different frameworks:

pnpm dev:react-vite     # TanStack Router
pnpm dev:react-router   # React Router v6
pnpm dev:next           # Next.js App Router
pnpm dev:shadcn         # shadcn component demo

Browser Support

• Chrome/Edge 90+
• Firefox 90+
• Safari 15+

License

MIT

---

Development

# Install dependencies
pnpm install

# Run example app
pnpm dev

# Run tests
pnpm test        # Unit tests
pnpm test:e2e    # Playwright E2E tests

# Build packages
pnpm build

# Lint and format
pnpm lint
pnpm format