Onboarding

What It Does

apps/mobile uses a QuickForm stepper onboarding flow that runs before the main app stack. The flow is schema-driven and extensible via filters.

When To Use

• You need to collect user profile data before first app usage.
• You need app-specific onboarding steps on top of the default flow.
• You need route-level onboarding extensions (/onboarding/[onboardingPath]).

Prerequisites

• Authenticated user session.
• completedOnboarding field available on user record.
• apps/mobile/config/onboarding.config.tsx configured.

Flow Overview

• app/(app)/_layout.tsx redirects users with !completedOnboarding to /onboarding.
• app/onboarding/index.tsx renders the default stepper flow.
• app/onboarding/[onboardingPath]/index.tsx supports custom onboarding routes from filters.

How To Use

Expand
Copy to Clipboardimport { z } from 'zod';
 
export const onboardingSchema = {
  userImageUrl: z.string().optional().nullable(),
  userName: z.string().trim().min(1).max(64),
  userPhone: z.string().trim().max(16).optional().or(z.literal('')),
  userEmail: z.string().email(),
  userRole: z.enum(['designer', 'programmer', 'product_manager', 'tester', 'marketer']),
};
 
export const onboardingStepsConfig = [
  {
    type: 'step',
    label: 'User',
    settings: [
      { type: 'user_media', slug: 'userImageUrl' },
      { type: 'text', slug: 'userName', label: 'Name' },
      { type: 'text', slug: 'userEmail', label: 'Email', disabled: true },
    ],
  },
  {
    type: 'step',
    label: 'Profession',
    settings: [{ type: 'question_select', slug: 'userRole' }],
  },
];
Expand

Copy to Clipboardimport { QuickForm } from '@kit/native-ui/quick-form';
import { applyAsyncFilter, useApplyFilter } from '@kit/utils/filters';
import { onboardingSchema, onboardingStepsConfig } from '~/config/onboarding.config';
 
const schema = useApplyFilter('get_onboarding_schema', onboardingSchema);
const steps = useApplyFilter('get_onboarding_steps_config', onboardingStepsConfig, { clientTrpc });
const extraInputs = useApplyFilter('get_onboarding_extra_inputs', {});
 
<QuickForm config={onboardingConfig} inputs={extraInputs} onSubmit={handleSubmit} />

Advanced Extension Points

Filter API

Mobile onboarding is extended through organization onboarding filters registered from the shared onboarding package layer.

MCP Context

Expand
Copy to Clipboardcapability: onboarding_mobile_flow
entrypoints:
  - apps/mobile/config/onboarding.config.tsx
  - apps/mobile/app/onboarding/index.tsx
  - apps/mobile/app/onboarding/[onboardingPath]/index.tsx
  - apps/mobile/app/(app)/_layout.tsx
  - apps/mobile/hooks/use-filters.ts
  - apps/mobile/config/i18n.config.ts
  - kit/organization/src/shared/filters/use-filters/use-onboarding-filters.tsx
  - kit/organization/src/native/filters/use-filters/use-onboarding-filters.tsx
  - kit/organization/src/native/filters/use-filters/use-translation-filters.tsx
inputs:
  - onboarding_schema
  - onboarding_steps
  - onboarding_filter_overrides
outputs:
  - gated_onboarding_experience
constraints:
  - user fields in steps must exist in schema
  - completedOnboarding gating must stay consistent with app layout redirect
side_effects:
  - updates user profile fields and onboarding completion status
Expand

Agent Recipe

1. Extend schema and steps in onboarding.config.tsx.
2. Add custom inputs/logic through onboarding filters instead of hardcoding package internals.
3. Verify completedOnboarding redirect behavior in (app)/_layout.tsx and onboarding submit path.

Troubleshooting

• If fields do not render, verify input type is registered in onboarding inputs map/filters.
• If user always returns to onboarding, verify updateUser mutation persists completion fields and user query refresh occurs.
• If custom onboarding path shows 404 (Unmatched), verify render_onboarding_path filter returns content.

Related

• Retrieve User
• Settings
• Web Onboarding