@geenius/onboarding

Guided onboarding flows, checklist state, framework bindings, and persistence providers for Geenius applications.

Install

pnpm add @geenius/onboarding

Add the peers you actually use:

• react and react-dom for @geenius/onboarding/react or @geenius/onboarding/react-css
• solid-js for @geenius/onboarding/solidjs or @geenius/onboarding/solidjs-css
• react-native for @geenius/onboarding/react-native
• convex for @geenius/onboarding/convex
• @neondatabase/serverless for @geenius/onboarding/neon
• Cloudflare KV and memory providers do not require an extra runtime peer

Available Exports

import { completeStep, computeProgress, configureOnboarding, createChecklistItems, defineFlow, userFlow } from '@geenius/onboarding'
import { OnboardingProvider, OnboardingWizard, useOnboarding } from '@geenius/onboarding/react'
import { OnboardingProvider as ReactCssProvider } from '@geenius/onboarding/react-css'
import { OnboardingProvider as SolidProvider, createOnboarding } from '@geenius/onboarding/solidjs'
import { OnboardingProvider as SolidCssProvider } from '@geenius/onboarding/solidjs-css'
import { OnboardingWizard as NativeOnboardingWizard } from '@geenius/onboarding/react-native'
import { onboardingSchema, startFlow } from '@geenius/onboarding/convex'
import { createNeonOnboardingProvider } from '@geenius/onboarding/neon'
import { createCloudflareKVOnboardingProvider } from '@geenius/onboarding/cloudflareKV'
import { createMemoryOnboardingProvider } from '@geenius/onboarding/memory'

The current green launch matrix and package export map cover react, react-css, solidjs, solidjs-css, react-native, convex, neon, cloudflareKV, and memory.

What This Package Owns

@geenius/onboarding ships:

• shared flow types, branded identifiers, validation helpers, and typed errors
• defineFlow() and StepDefinition authoring helpers for ordered, prerequisite-aware starter flows
• computeProgress() and completeStep() helpers for shared progress summaries and persistence snapshots
• bundled onboarding flows for user, admin, and developer roles
• React hooks/providers and SolidJS primitives/providers for the active launch matrix
• React Native providers, native primitives, accessibility labels, and testID selectors
• Tailwind and vanilla CSS UI variants for wizards, progress, checklist, modal, and page surfaces
• the launch export matrix for React, SolidJS, React Native, and persistence providers
• Convex schema, validators, queries, and mutations for onboarding persistence
• Neon, Cloudflare KV, and memory persistence providers

Basic Usage

import { OnboardingProvider, OnboardingWizard } from '@geenius/onboarding/react'
import { userFlow } from '@geenius/onboarding'

const stepComponents = {
  WelcomeStep: () => <div>Welcome to your workspace</div>,
  ProfileStep: () => <div>Profile setup goes here</div>,
  LaunchStep: () => <div>Launch checklist goes here</div>,
}

export function OnboardingRoute() {
  return (
    <OnboardingProvider flow={userFlow}>
      <OnboardingWizard stepComponents={stepComponents} />
    </OnboardingProvider>
  )
}

Authored Flow Definitions

Use defineFlow() when you want a typed authoring shape with plain string IDs, explicit step order, optional steps, initial completion state, and prerequisite ordering. The helper brands IDs, sorts ordered/prerequisite steps, and returns a normalized OnboardingFlow.

import { defineFlow } from '@geenius/onboarding'

export const launchFlow = defineFlow({
  id: 'launch-flow',
  role: 'developer',
  title: 'Launch setup',
  description: 'Prepare the workspace for first deploy.',
  steps: [
    {
      id: 'welcome',
      title: 'Welcome',
      description: 'Review the launch path.',
      order: 10,
      isCompleted: true,
    },
    {
      id: 'environment',
      title: 'Prepare the environment',
      description: 'Install tools and validate credentials.',
      order: 20,
    },
    {
      id: 'deploy',
      title: 'Review deploy',
      description: 'Confirm rollback and deploy expectations.',
      order: 30,
      isOptional: true,
      prerequisites: ['environment'],
    },
  ],
})

CSS Variants

The CSS variants are standalone vanilla-CSS implementations. Import the runtime and stylesheet together:

import '@geenius/onboarding/react-css/styles.css'
import { OnboardingProvider, OnboardingWizard } from '@geenius/onboarding/react-css'

import '@geenius/onboarding/solidjs-css/styles.css'
import { OnboardingProvider, OnboardingWizard } from '@geenius/onboarding/solidjs-css'

Convex Usage

import { onboardingSchema, startFlow, completeStep } from '@geenius/onboarding/convex'

Use onboardingSchema or onboardingTables when merging package tables into an application schema.

Storybook Review Apps

The repository includes Storybook V2 review apps, and the manifest-driven runner filters the active in-scope variants by default. Use it to build or test the current review surface:

pnpm storybook:build
pnpm test:storybook

Contributing Tests

variants.json is the single source of truth for the launch matrix. Add or update a variant there first, then add the package source, exports, harness coverage, Storybook registration, and bundle budget that correspond to that manifest entry.

Use these local gates while contributing:

pnpm lint
pnpm lint:apps
pnpm test
pnpm size
pnpm audit:supply-chain
pnpm test:license
pnpm test:e2e -- --project=react-chromium
pnpm test:visual
pnpm test:visual:full -- --update-snapshots

test:gauntlet is the PR-blocking suite. test:all adds Storybook builds, Playwright a11y/visual/perf, DB migration checks, and coverage aggregation for nightly or pre-release validation.

License

FSL-1.1-Apache-2.0