Skip to main content

​
Overview

Launch ships with a lightweight onboarding flow that helps you capture the minimum profile data needed to personalize the app, then request permissions only when they are relevant. The default flow collects a name, optionally verifies a phone number via SMS OTP, and asks for push notification permissions. Onboarding is the moment to build trust, set expectations, and gather the data that improves first-run UX. The current flow is intentionally short so you can expand it based on your product needs.

​
Prerequisites

  • Auth flow enabled
  • Onboarding routes available in apps/mobile/app/onboarding

​
Current flow

The onboarding screens live in apps/mobile/app/onboarding/:
  • welcome.tsx collects the user’s name
  • phone.tsx collects a phone number for SMS OTP
  • verify-otp.tsx verifies the OTP
  • push-notifications.tsx requests push permissions
The flow is controlled by the feature registry and can skip SMS entirely if you do not want to set up Twilio yet. Push notifications in onboarding currently store the user’s preference, but do not enable real notifications until you complete the push notification setup later in the docs.

​
Flow control

Routing and step selection are handled in:
  • apps/mobile/app/_layout.tsx
  • apps/mobile/lib/hooks/useAppNavigation.ts

​
Feature registry (SMS / OTP)

The SMS OTP step is gated by the oneSignal feature flag in apps/mobile/features/feature-registry.tsx. When the flag is disabled, the flow skips phone.tsx and verify-otp.tsx so onboarding becomes:
  1. Name
  2. Push notifications
This lets you ship without SMS while keeping the flow intact.

​
OneSignal and SMS OTP

OneSignal and SMS OTP configuration are covered in OneSignal and SMS OTP. If you are not using SMS in your onboarding flow, disable the feature registry flag and skip the phone and OTP steps.

​
How the backend supports onboarding

The API exposes user endpoints that save onboarding data and track completion. They live in apps/api/src/routers/user.ts and include:
  • user.saveName
  • user.savePhoneNumber
  • user.sendPhoneOtp
  • user.verifyPhoneOtp
  • user.registerDeviceToken
  • user.markOnboardingComplete
  • user.onboardingStatus
These endpoints update the user profile and onboarding flags in the database.

​
Data model references

Onboarding fields are stored on the User model in apps/api/prisma/schema.prisma, including name, phone number, and onboarding completion flags. Push notification device tokens are stored in the DeviceToken model.

​
Extending onboarding

To add steps:
  1. Create a new file in apps/mobile/app/onboarding/.
  2. Add routing logic in useAppNavigation.ts if the step should be required.
  3. Link from the prior step using the router.
Common additions include:
  • A short goal or preferences questionnaire
  • A paywall before the main app (if your product is subscription-first)
  • An account personalization step (avatar, username, interests)
If you add new onboarding data, create a matching endpoint in apps/api/src/routers/user.ts and persist it on the User model in apps/api/prisma/schema.prisma.

​
Code references

  • Root Layout: apps/mobile/app/_layout.tsx
  • Onboarding Screens: apps/mobile/app/onboarding/*.tsx
  • Navigation Logic: apps/mobile/lib/hooks/useAppNavigation.ts
  • User Endpoints: apps/api/src/routers/user.ts
  • Database Schema: apps/api/prisma/schema.prisma

​
Best practices

  • Keep early steps short and low-friction.
  • Ask for permissions only after explaining the benefit.
  • Add a paywall only if it matches your product’s activation strategy.
  • Track each step so you can measure drop-off and improve completion.