Getting SaaS onboarding right is the difference between a product that grows and one that leaks users. This guide covers the full architecture for building production-grade onboarding flows with TypeScript — from data modeling and state management to step orchestration and analytics. Every code example is typed, tested, and extracted from real implementations.
Defining Activation Metrics Before Writing Code
Before designing the onboarding flow, define your activation metric. This is the single action (or combination of actions) that correlates most strongly with long-term retention.
typescript
1// Define your activation criteria explicitly
2interface ActivationCriteria {
3 requiredActions: ActivationAction[];
4 timeWindowHours: number;
5 correlationWithRetention: number; // From your data analysis
6}
7
8interface ActivationAction {
9 actionId: string;
10 description: string;
11 weight: number; // Relative importance
12}
13
14const activationCriteria: ActivationCriteria = {
15 requiredActions: [
16 {
17 actionId: 'create_first_project',
18 description: 'User creates their first project',
19 weight: 0.4,
20 },
21 {
22 actionId: 'invite_teammate',
23 description: 'User invites at least one teammate',
24 weight: 0.35,
25 },
26 {
27 actionId: 'complete_first_task',
28 description: 'User marks a task as done',
29 weight: 0.25,
30 },
31 ],
32 timeWindowHours: 48,
33 correlationWithRetention: 0.73,
34};
35
The activation metric drives every design decision in the onboarding flow. Each step should push the user toward completing one of these actions.
Data Model: Onboarding State Machine
Onboarding progress is a state machine. Each step transitions through well-defined states, and the overall flow has its own lifecycle.
typescript
1// Core types for the onboarding state machine
2type StepStatus = 'locked' | 'available' | 'in_progress' | 'completed' | 'skipped';
3type FlowStatus = 'not_started' | 'in_progress' | 'completed' | 'dismissed';
4
5interface OnboardingStep {
6 id: string;
7 title: string;
8 description: string;
9 status: StepStatus;
10 required: boolean;
11 order: number;
12 dependsOn: string[];
13 startedAt: Date | null;
14 completedAt: Date | null;
15 metadata: Record<string, unknown>;
16}
17
18interface OnboardingFlow {
19 userId: string;
20 flowId: string;
21 variant: string; // A/B test variant
22 status: FlowStatus;
23 steps: OnboardingStep[];
24 startedAt: Date;
25 completedAt: Date | null;
26 dismissedAt: Date | null;
27 lastActiveAt: Date;
28}
29
30// Database schema (PostgreSQL with Prisma)
31// prisma/schema.prisma equivalent:
32/*
33model OnboardingFlow {
34 id String @id @default(cuid())
35 userId String @unique
36 flowId String
37 variant String
38 status String @default("not_started")
39 startedAt DateTime @default(now())
40 completedAt DateTime?
41 dismissedAt DateTime?
42 lastActiveAt DateTime @default(now())
43 steps OnboardingStep[]
44
45 @@index([userId])
46 @@index([status])
47}
48
49model OnboardingStep {
50 id String @id @default(cuid())
51 flowId String
52 stepKey String
53 title String
54 description String
55 status String @default("locked")
56 required Boolean @default(true)
57 order Int
58 dependsOn String[] @default([])
59 startedAt DateTime?
60 completedAt DateTime?
61 metadata Json @default("{}")
62 flow OnboardingFlow @relation(fields: [flowId], references: [id])
63
64 @@unique([flowId, stepKey])
65 @@index([flowId])
66}
67*/
68
Step Orchestrator: Determining Available Steps
The orchestrator evaluates dependencies and conditions to determine which steps are available at any point.
typescript
1class StepOrchestrator {
2 constructor(private flow: OnboardingFlow) {}
3
4 getAvailableSteps(): OnboardingStep[] {
5 return this.flow.steps.filter(step => {
6 if (step.status === 'completed' || step.status === 'skipped') return false;
7
8 const dependenciesMet = step.dependsOn.every(depId => {
9 const dep = this.flow.steps.find(s => s.id === depId);
10 return dep?.status === 'completed' || dep?.status === 'skipped';
11 });
12
13 return dependenciesMet;
14 });
15 }
16
17 getNextStep(): OnboardingStep | null {
18 const available = this.getAvailableSteps();
19 // Prioritize required steps, then sort by order
20 return available.sort((a, b) => {
21 if (a.required !== b.required) return a.required ? -1 : 1;
22 return a.order - b.order;
23 })[0] ?? null;
24 }
25
26 canComplete(stepId: string): boolean {
27 const step = this.flow.steps.find(s => s.id === stepId);
28 if (!step) return false;
29 return step.status === 'available' || step.status === 'in_progress';
30 }
31
32 isFlowComplete(): boolean {
33 const requiredSteps = this.flow.steps.filter(s => s.required);
34 return requiredSteps.every(
35 s => s.status === 'completed' || s.status === 'skipped'
36 );
37 }
38
39 getCompletionPercentage(): number {
40 const total = this.flow.steps.length;
41 if (total === 0) return 100;
42 const done = this.flow.steps.filter(
43 s => s.status === 'completed' || s.status === 'skipped'
44 ).length;
45 return Math.round((done / total) * 100);
46 }
47}
48
Flow Definitions: Template-Based Initialization
Define onboarding flows as templates that get instantiated per user. Different user segments get different flows.
typescript
1interface FlowTemplate {
2 flowId: string;
3 name: string;
4 targetSegment: (user: UserProfile) => boolean;
5 steps: StepTemplate[];
6}
7
8interface StepTemplate {
9 stepKey: string;
10 title: string;
11 description: string;
12 required: boolean;
13 order: number;
14 dependsOn: string[];
15 condition?: (user: UserProfile) => boolean;
16}
17
18const flowTemplates: FlowTemplate[] = [
19 {
20 flowId: 'team-onboarding-v2',
21 name: 'Team Onboarding',
22 targetSegment: (user) => user.plan !== 'solo' && user.teamSize > 1,
23 steps: [
24 {
25 stepKey: 'create_workspace',
26 title: 'Create your workspace',
27 description: 'Set up your team workspace with a name and basic settings.',
28 required: true,
29 order: 1,
30 dependsOn: [],
31 },
32 {
33 stepKey: 'create_first_project',
34 title: 'Create your first project',
35 description: 'Start a project to organize your team\'s work.',
36 required: true,
37 order: 2,
38 dependsOn: ['create_workspace'],
39 },
40 {
41 stepKey: 'invite_teammates',
42 title: 'Invite your team',
43 description: 'Add teammates to collaborate on projects.',
44 required: true,
45 order: 3,
46 dependsOn: ['create_workspace'],
47 },
48 {
49 stepKey: 'create_first_task',
50 title: 'Create a task',
51 description: 'Add your first task to track work.',
52 required: true,
53 order: 4,
54 dependsOn: ['create_first_project'],
55 },
56 {
57 stepKey: 'connect_integration',
58 title: 'Connect an integration',
59 description: 'Link Slack, GitHub, or other tools your team uses.',
60 required: false,
61 order: 5,
62 dependsOn: ['create_workspace'],
63 condition: (user) => user.plan === 'pro' || user.plan === 'enterprise',
64 },
65 ],
66 },
67 {
68 flowId: 'solo-onboarding-v2',
69 name: 'Solo Onboarding',
70 targetSegment: (user) => user.plan === 'solo' || user.teamSize <= 1,
71 steps: [
72 {
73 stepKey: 'create_first_project',
74 title: 'Create your first project',
75 description: 'Start a project to organize your work.',
76 required: true,
77 order: 1,
78 dependsOn: [],
79 },
80 {
81 stepKey: 'create_first_task',
82 title: 'Add a task',
83 description: 'Create your first task to start tracking work.',
84 required: true,
85 order: 2,
86 dependsOn: ['create_first_project'],
87 },
88 {
89 stepKey: 'customize_view',
90 title: 'Customize your view',
91 description: 'Switch between board, list, and calendar views.',
92 required: false,
93 order: 3,
94 dependsOn: ['create_first_project'],
95 },
96 ],
97 },
98];
99
100function initializeFlow(user: UserProfile): OnboardingFlow {
101 const template = flowTemplates.find(t => t.targetSegment(user));
102 if (!template) throw new Error(`No matching flow template for user ${user.id}`);
103
104 const steps: OnboardingStep[] = template.steps
105 .filter(s => !s.condition || s.condition(user))
106 .map(s => ({
107 id: `${template.flowId}-${s.stepKey}`,
108 title: s.title,
109 description: s.description,
110 status: s.dependsOn.length === 0 ? 'available' : 'locked',
111 required: s.required,
112 order: s.order,
113 dependsOn: s.dependsOn.map(d => `${template.flowId}-${d}`),
114 startedAt: null,
115 completedAt: null,
116 metadata: {},
117 }));
118
119 return {
120 userId: user.id,
121 flowId: template.flowId,
122 variant: 'control',
123 status: 'not_started',
124 steps,
125 startedAt: new Date(),
126 completedAt: null,
127 dismissedAt: null,
128 lastActiveAt: new Date(),
129 };
130}
131
API Layer: Express Routes with Validation
typescript
1import { Router, Request, Response } from 'express';
2import { z } from 'zod';
3
4const router = Router();
5
6const CompleteStepSchema = z.object({
7 stepId: z.string().min(1),
8 metadata: z.record(z.unknown()).optional().default({}),
9});
10
11router.get('/onboarding/progress', async (req: Request, res: Response) => {
12 const userId = req.user!.id;
13
14 const flow = await prisma.onboardingFlow.findUnique({
15 where: { userId },
16 include: { steps: { orderBy: { order: 'asc' } } },
17 });
18
19 if (!flow) {
20 const userProfile = await getUserProfile(userId);
21 const newFlow = initializeFlow(userProfile);
22 const saved = await prisma.onboardingFlow.create({
23 data: {
24 ...newFlow,
25 steps: { create: newFlow.steps },
26 },
27 include: { steps: true },
28 });
29 return res.json(saved);
30 }
31
32 res.json(flow);
33});
34
35router.post('/onboarding/complete', async (req: Request, res: Response) => {
36 const userId = req.user!.id;
37 const { stepId, metadata } = CompleteStepSchema.parse(req.body);
38
39 const flow = await prisma.onboardingFlow.findUnique({
40 where: { userId },
41 include: { steps: true },
42 });
43
44 if (!flow) return res.status(404).json({ error: 'No onboarding flow found' });
45
46 const orchestrator = new StepOrchestrator(flow as unknown as OnboardingFlow);
47
48 if (!orchestrator.canComplete(stepId)) {
49 return res.status(400).json({ error: 'Step cannot be completed in current state' });
50 }
51
52 const now = new Date();
53
54 await prisma.$transaction([
55 prisma.onboardingStep.update({
56 where: { flowId_stepKey: { flowId: flow.id, stepKey: stepId } },
57 data: { status: 'completed', completedAt: now, metadata },
58 }),
59 prisma.onboardingFlow.update({
60 where: { userId },
61 data: { lastActiveAt: now },
62 }),
63 ]);
64
65 // Unlock dependent steps
66 const updatedFlow = await prisma.onboardingFlow.findUnique({
67 where: { userId },
68 include: { steps: true },
69 });
70
71 const updatedOrchestrator = new StepOrchestrator(updatedFlow as unknown as OnboardingFlow);
72
73 if (updatedOrchestrator.isFlowComplete()) {
74 await prisma.onboardingFlow.update({
75 where: { userId },
76 data: { status: 'completed', completedAt: now },
77 });
78 }
79
80 // Emit analytics event
81 await emitOnboardingEvent({
82 type: 'step_completed',
83 userId,
84 stepId,
85 flowId: flow.flowId,
86 variant: flow.variant,
87 timestamp: now,
88 metadata,
89 });
90
91 res.json(updatedFlow);
92});
93
94router.post('/onboarding/skip', async (req: Request, res: Response) => {
95 const userId = req.user!.id;
96 const { stepId } = z.object({ stepId: z.string() }).parse(req.body);
97
98 const flow = await prisma.onboardingFlow.findUnique({
99 where: { userId },
100 include: { steps: true },
101 });
102
103 if (!flow) return res.status(404).json({ error: 'No onboarding flow found' });
104
105 const step = flow.steps.find(s => s.stepKey === stepId);
106 if (!step) return res.status(404).json({ error: 'Step not found' });
107 if (step.required) return res.status(400).json({ error: 'Required steps cannot be skipped' });
108
109 await prisma.onboardingStep.update({
110 where: { flowId_stepKey: { flowId: flow.id, stepKey: stepId } },
111 data: { status: 'skipped', completedAt: new Date() },
112 });
113
114 await emitOnboardingEvent({
115 type: 'step_skipped',
116 userId,
117 stepId,
118 flowId: flow.flowId,
119 variant: flow.variant,
120 timestamp: new Date(),
121 });
122
123 const updatedFlow = await prisma.onboardingFlow.findUnique({
124 where: { userId },
125 include: { steps: { orderBy: { order: 'asc' } } },
126 });
127
128 res.json(updatedFlow);
129});
130
131router.post('/onboarding/dismiss', async (req: Request, res: Response) => {
132 const userId = req.user!.id;
133
134 await prisma.onboardingFlow.update({
135 where: { userId },
136 data: { status: 'dismissed', dismissedAt: new Date() },
137 });
138
139 await emitOnboardingEvent({
140 type: 'flow_dismissed',
141 userId,
142 flowId: 'unknown',
143 variant: 'unknown',
144 timestamp: new Date(),
145 });
146
147 res.json({ success: true });
148});
149
150export default router;
151
Need a second opinion on your saas engineering architecture?
I run free 30-minute strategy calls for engineering teams tackling this exact problem.
Book a Free CallClient-Side Integration: React Hooks
The React integration provides a clean hook-based API for consuming onboarding state throughout the application.
typescript
1import { createContext, useContext, useEffect, useState, useCallback, ReactNode } from 'react';
2
3interface OnboardingContextValue {
4 flow: OnboardingFlow | null;
5 currentStep: OnboardingStep | null;
6 completionPercentage: number;
7 isComplete: boolean;
8 isDismissed: boolean;
9 loading: boolean;
10 completeStep: (stepId: string, metadata?: Record<string, unknown>) => Promise<void>;
11 skipStep: (stepId: string) => Promise<void>;
12 dismiss: () => Promise<void>;
13}
14
15const OnboardingContext = createContext<OnboardingContextValue | null>(null);
16
17export function OnboardingProvider({ children }: { children: ReactNode }) {
18 const [flow, setFlow] = useState<OnboardingFlow | null>(null);
19 const [loading, setLoading] = useState(true);
20
21 useEffect(() => {
22 const loadFlow = async () => {
23 try {
24 const response = await fetch('/api/onboarding/progress', {
25 credentials: 'include',
26 });
27 if (response.ok) {
28 setFlow(await response.json());
29 }
30 } finally {
31 setLoading(false);
32 }
33 };
34 loadFlow();
35 }, []);
36
37 const completeStep = useCallback(async (
38 stepId: string,
39 metadata: Record<string, unknown> = {}
40 ) => {
41 const response = await fetch('/api/onboarding/complete', {
42 method: 'POST',
43 headers: { 'Content-Type': 'application/json' },
44 credentials: 'include',
45 body: JSON.stringify({ stepId, metadata }),
46 });
47 if (response.ok) {
48 setFlow(await response.json());
49 }
50 }, []);
51
52 const skipStep = useCallback(async (stepId: string) => {
53 const response = await fetch('/api/onboarding/skip', {
54 method: 'POST',
55 headers: { 'Content-Type': 'application/json' },
56 credentials: 'include',
57 body: JSON.stringify({ stepId }),
58 });
59 if (response.ok) {
60 setFlow(await response.json());
61 }
62 }, []);
63
64 const dismiss = useCallback(async () => {
65 const response = await fetch('/api/onboarding/dismiss', {
66 method: 'POST',
67 credentials: 'include',
68 });
69 if (response.ok) {
70 setFlow(prev => prev ? { ...prev, status: 'dismissed' } : null);
71 }
72 }, []);
73
74 const orchestrator = flow ? new StepOrchestrator(flow) : null;
75
76 const value: OnboardingContextValue = {
77 flow,
78 currentStep: orchestrator?.getNextStep() ?? null,
79 completionPercentage: orchestrator?.getCompletionPercentage() ?? 0,
80 isComplete: flow?.status === 'completed',
81 isDismissed: flow?.status === 'dismissed',
82 loading,
83 completeStep,
84 skipStep,
85 dismiss,
86 };
87
88 return (
89 <OnboardingContext.Provider value={value}>
90 {children}
91 </OnboardingContext.Provider>
92 );
93}
94
95export function useOnboarding(): OnboardingContextValue {
96 const context = useContext(OnboardingContext);
97 if (!context) {
98 throw new Error('useOnboarding must be used within OnboardingProvider');
99 }
100 return context;
101}
102
Onboarding Checklist Component
typescript
1import { motion, AnimatePresence } from 'motion/react';
2
3function OnboardingChecklist() {
4 const { flow, currentStep, completionPercentage, isComplete, isDismissed, completeStep, skipStep, dismiss } = useOnboarding();
5 const [expanded, setExpanded] = useState(true);
6
7 if (!flow || isComplete || isDismissed) return null;
8
9 return (
10 <div className="fixed bottom-4 right-4 w-80 bg-white rounded-lg shadow-xl border z-50">
11 <button
12 onClick={() => setExpanded(!expanded)}
13 className="w-full flex items-center justify-between p-4 text-left"
14 >
15 <div>
16 <h3 className="font-semibold text-sm">Getting Started</h3>
17 <p className="text-xs text-gray-500">{completionPercentage}% complete</p>
18 </div>
19 <div className="w-8 h-8 rounded-full bg-blue-50 flex items-center justify-center">
20 <span className="text-xs font-medium text-blue-600">{completionPercentage}%</span>
21 </div>
22 </button>
23
24 <AnimatePresence>
25 {expanded && (
26 <motion.div
27 initial={{ height: 0, opacity: 0 }}
28 animate={{ height: 'auto', opacity: 1 }}
29 exit={{ height: 0, opacity: 0 }}
30 className="overflow-hidden"
31 >
32 <div className="px-4 pb-4 space-y-2">
33 {/* Progress bar */}
34 <div className="w-full bg-gray-100 rounded-full h-1.5 mb-3">
35 <motion.div
36 className="bg-blue-600 h-1.5 rounded-full"
37 initial={{ width: 0 }}
38 animate={{ width: `${completionPercentage}%` }}
39 transition={{ duration: 0.5 }}
40 />
41 </div>
42
43 {flow.steps.map(step => (
44 <OnboardingStepItem
45 key={step.id}
46 step={step}
47 isCurrent={currentStep?.id === step.id}
48 onComplete={() => completeStep(step.id)}
49 onSkip={() => skipStep(step.id)}
50 />
51 ))}
52
53 <button
54 onClick={dismiss}
55 className="text-xs text-gray-400 hover:text-gray-600 mt-2"
56 >
57 Dismiss checklist
58 </button>
59 </div>
60 </motion.div>
61 )}
62 </AnimatePresence>
63 </div>
64 );
65}
66
67function OnboardingStepItem({
68 step,
69 isCurrent,
70 onComplete,
71 onSkip,
72}: {
73 step: OnboardingStep;
74 isCurrent: boolean;
75 onComplete: () => void;
76 onSkip: () => void;
77}) {
78 return (
79 <div
80 className={`flex items-start gap-3 p-2 rounded ${
81 isCurrent ? 'bg-blue-50 border border-blue-200' : ''
82 }`}
83 >
84 <div className="mt-0.5">
85 {step.status === 'completed' ? (
86 <div className="w-5 h-5 rounded-full bg-green-500 flex items-center justify-center">
87 <svg className="w-3 h-3 text-white" fill="none" viewBox="0 0 24 24" stroke="currentColor">
88 <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={3} d="M5 13l4 4L19 7" />
89 </svg>
90 </div>
91 ) : step.status === 'skipped' ? (
92 <div className="w-5 h-5 rounded-full bg-gray-300" />
93 ) : (
94 <div className={`w-5 h-5 rounded-full border-2 ${
95 isCurrent ? 'border-blue-500' : 'border-gray-300'
96 }`} />
97 )}
98 </div>
99
100 <div className="flex-1 min-w-0">
101 <p className={`text-sm font-medium ${
102 step.status === 'completed' ? 'line-through text-gray-400' : 'text-gray-900'
103 }`}>
104 {step.title}
105 </p>
106 {isCurrent && (
107 <p className="text-xs text-gray-500 mt-0.5">{step.description}</p>
108 )}
109 {isCurrent && !step.required && (
110 <button onClick={onSkip} className="text-xs text-gray-400 hover:text-gray-600 mt-1">
111 Skip for now
112 </button>
113 )}
114 </div>
115 </div>
116 );
117}
118
Analytics: Tracking Onboarding Events
typescript
1interface OnboardingEvent {
2 type: 'flow_started' | 'step_started' | 'step_completed' | 'step_skipped' | 'flow_completed' | 'flow_dismissed';
3 userId: string;
4 flowId: string;
5 variant: string;
6 stepId?: string;
7 timestamp: Date;
8 metadata?: Record<string, unknown>;
9 durationMs?: number;
10}
11
12class OnboardingAnalytics {
13 constructor(private readonly analyticsClient: AnalyticsClient) {}
14
15 async trackEvent(event: OnboardingEvent): Promise<void> {
16 // Calculate duration for step completion events
17 if (event.type === 'step_completed' && event.stepId) {
18 const startEvent = await this.getLastEvent(
19 event.userId,
20 event.stepId,
21 'step_started'
22 );
23 if (startEvent) {
24 event.durationMs = event.timestamp.getTime() - startEvent.timestamp.getTime();
25 }
26 }
27
28 await this.analyticsClient.track({
29 event: `onboarding.${event.type}`,
30 userId: event.userId,
31 properties: {
32 flowId: event.flowId,
33 variant: event.variant,
34 stepId: event.stepId,
35 durationMs: event.durationMs,
36 ...event.metadata,
37 },
38 timestamp: event.timestamp,
39 });
40 }
41
42 async getFunnelMetrics(flowId: string, dateRange: DateRange): Promise<FunnelMetrics> {
43 const query = `
44 SELECT
45 step_id,
46 COUNT(DISTINCT user_id) AS users_reached,
47 COUNT(DISTINCT CASE WHEN event_type = 'step_completed' THEN user_id END) AS users_completed,
48 AVG(duration_ms) FILTER (WHERE event_type = 'step_completed') AS avg_duration_ms,
49 PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY duration_ms)
50 FILTER (WHERE event_type = 'step_completed') AS median_duration_ms
51 FROM onboarding_events
52 WHERE flow_id = $1
53 AND timestamp BETWEEN $2 AND $3
54 GROUP BY step_id
55 ORDER BY MIN(timestamp)
56 `;
57
58 return this.analyticsClient.query(query, [flowId, dateRange.start, dateRange.end]);
59 }
60
61 private async getLastEvent(
62 userId: string,
63 stepId: string,
64 type: string
65 ): Promise<OnboardingEvent | null> {
66 return this.analyticsClient.findOne({
67 userId,
68 stepId,
69 type,
70 });
71 }
72}
73
A/B Testing Onboarding Variants
typescript
1import { createHash } from 'crypto';
2
3interface ABTestConfig {
4 testId: string;
5 variants: { id: string; weight: number }[];
6}
7
8function assignVariant(userId: string, test: ABTestConfig): string {
9 // Deterministic assignment based on user ID
10 const hash = createHash('md5')
11 .update(`${userId}:${test.testId}`)
12 .digest('hex');
13 const bucket = parseInt(hash.substring(0, 8), 16) / 0xffffffff;
14
15 let cumulative = 0;
16 for (const variant of test.variants) {
17 cumulative += variant.weight;
18 if (bucket <= cumulative) return variant.id;
19 }
20
21 return test.variants[test.variants.length - 1].id;
22}
23
24// Usage
25const onboardingTest: ABTestConfig = {
26 testId: 'onboarding-flow-v2-2024',
27 variants: [
28 { id: 'control', weight: 0.5 },
29 { id: 'progressive', weight: 0.5 },
30 ],
31};
32
33const variant = assignVariant(user.id, onboardingTest);
34
Production Checklist
Before deploying your onboarding flow, verify these items:
- Every required step maps to an activation action. If a step doesn't contribute to activation, make it optional or remove it.
- Steps fail gracefully. If the API is unreachable, the onboarding UI degrades without blocking core product usage.
- Progress persists across sessions. Users who close their browser and return should see their previous progress.
- Completion events are idempotent. Double-submitting a step completion doesn't break state or double-count analytics.
- Flow assignment is deterministic. The same user always gets the same A/B variant and flow template.
- Dismissal is permanent. Once a user dismisses onboarding, it stays dismissed until explicitly re-triggered.
- Mobile responsiveness. The checklist widget adapts to mobile viewports without blocking content.
- Analytics pipeline handles backpressure. If the analytics service is slow, onboarding interactions remain unaffected.
Conclusion
Building SaaS onboarding flows in TypeScript gives you the type safety needed to manage complex state transitions across multiple user segments. The core architecture — flow templates, a step orchestrator, persistent state, and event-driven analytics — scales from simple three-step flows to enterprise onboarding with dozens of conditional paths.
The most common mistake is treating onboarding as a one-time build. In reality, the flow needs continuous iteration based on funnel data. Build the analytics pipeline alongside the onboarding logic, not after, so you have data from the first cohort of users.
Type safety across the entire stack — from database models through API validation to React component props — catches step ordering bugs, missing dependency declarations, and invalid state transitions at compile time rather than in production. That alone justifies the investment in proper TypeScript modeling over a quick JavaScript implementation.