onboardjs/onboardjs-skills

Overview

This skill integrates OnboardJS into React and Next.js projects to build reliable, headless user onboarding flows. It provides provider and hook patterns, step component conventions, persistence strategies, and optional Next.js client-side setup. Use it to manage flow state, navigation logic, conditional steps, and data persistence while keeping UI fully custom.

How this skill works

The skill wires up OnboardingProvider and the useOnboarding hook to expose renderStep, navigation helpers, and a normalized state object. You define an array of step configs (id, component, payload, nextStep/condition) and OnboardJS handles transition logic, validation flags, and persistence. For Next.js it enforces client components and offers dynamic imports to avoid SSR issues and reduce bundle size.

When to use it

• Setting up OnboardJS in a React or Next.js project
• Building multi-step wizards, guided flows, or onboarding tours
• Implementing conditional navigation or step visibility based on user data
• Persisting onboarding progress to localStorage or a custom backend
• Hydrating onboarding state safely in client-rendered Next.js pages

Best practices

• Export a canonical STEP_IDS array to calculate progress reliably instead of relying on missing step arrays in state
• Mark all step components and provider wrappers with "use client" when using Next.js App Router
• Lazy-load large or rarely used step components via dynamic imports to shrink initial bundle
• Keep step payloads lightweight; store heavy or sensitive data in backend persistence hooks
• Use nextStep as a function for conditional routing and condition for conditional visibility to keep flow logic declarative

Example use cases

• Welcome wizard that collects profile details, preferences, and final confirmation with a progress bar
• Role-based flow that routes admins to admin-setup steps and regular users to user-setup steps
• Multi-step form with field-level validation enabling/disabling Next until required fields are valid
• Persist onboarding progress to localStorage with TTL or to an API for logged-in users
• Next.js App Router onboarding page using a client wrapper and dynamic imports for steps