SaaS Customer Onboarding: Turning Signups into Active, Paid Users

1,000 website visitors
   → 50 signups (5% conversion)
     → 25 complete setup (50% activation)
       → 10 reach "aha moment" (40% of activated)
         → 5 convert to paid (50% conversion)
           → 3 remain active after 90 days (60% retention)

// components/onboarding/ValuePreview.tsx
function ValuePreview() {
  return (
    <div className="onboarding-step">
      <h2>See what your dashboard will look like</h2>
      <div className="mockup-container">
        <DashboardMockup /> {/* Pre-rendered example */}
      </div>
      <p className="hint">
        Your actual data will appear here once configured.
        This is what it will look like.
      </p>
      <button onClick={() => startSetup()}>
        Start Setup (2 minutes)
      </button>
    </div>
  )
}

// server/onboarding.ts
export const completeQuickStart = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: {
    data: {
      companyName: string
      productType: string
    }
  }) => {
    // Only ask for essential info in the first session
    await context.env.DB.prepare(`
      UPDATE users SET
        company_name = ?,
        product_type = ?,
        onboarding_step = 'first_dashboard'
      WHERE id = ?
    `).bind(data.companyName, data.productType, context.user.id).run()

    // Generate initial data based on product type
    await generateSampleData(context.user.id, data.productType)

    return { redirectTo: "/dashboard" }
  }
)

// components/onboarding/Checklist.tsx
type OnboardingStep = {
  id: string
  title: string
  description: string
  isComplete: boolean
  link: string
}

function OnboardingChecklist({ steps }: { steps: OnboardingStep[] }) {
  const completed = steps.filter((s) => s.isComplete).length

  return (
    <div className="onboarding-checklist">
      <div className="progress-bar">
        <div
          className="progress-fill"
          style={{ width: `${(completed / steps.length) * 100}%` }}
        />
      </div>
      <p className="progress-text">
        {completed} of {steps.length} steps complete
      </p>
      <ul>
        {steps.map((step) => (
          <li key={step.id} className={step.isComplete ? "done" : "pending"}>
            {step.isComplete ? (
              <CheckIcon />
            ) : (
              <Link to={step.link}>
                <span>{step.title}</span>
                <span className="description">{step.description}</span>
              </Link>
            )}
          </li>
        ))}
      </ul>
    </div>
  )
}

// Fetch user's current capability level
const capabilityLevel = await context.env.DB.prepare(`
  SELECT onboarding_step, features_unlocked
  FROM users WHERE id = ?
`).bind(userId).first()

// Only show advanced features if the basics are done
const features = capabilityLevel.features_unlocked
  ? allFeatures
  : allFeatures.filter((f) => !f.requiresSetup)

// components/EmptyState.tsx
function EmptySubscriptionList() {
  return (
    <div className="empty-state">
      <Icon name="subscriptions" />
      <h3>No subscriptions yet</h3>
      <p>Your first subscription is a few clicks away.</p>
      <Button onClick={() => navigate("/settings/stripe")}>
        Connect Stripe → See subscriptions in seconds
      </Button>
    </div>
  )
}

// server/onboarding/tracking.ts
export const trackOnboardingStep = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: {
    data: { step: string; duration: number; error?: string }
  }) => {
    await context.env.DB.prepare(`
      INSERT INTO onboarding_events
        (id, user_id, step, duration_ms, error, created_at)
      VALUES (?, ?, ?, ?, ?, ?)
    `).bind(
      crypto.randomUUID(),
      context.user.id,
      data.step,
      data.duration,
      data.error ?? null,
      Date.now()
    ).run()
  }
)

// Assign user to a variant
export const getOnboardingVariant = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const variants = ["guided_checklist", "progressive_disclosure", "video_tour"]
    const index = Math.abs(hashString(context.user.id)) % variants.length
    const variant = variants[index]

    // Track assignment
    await context.env.DB.prepare(`
      INSERT INTO ab_tests
        (id, user_id, test_name, variant, created_at)
      VALUES (?, ?, 'onboarding_flow', ?, ?)
    `).bind(crypto.randomUUID(), context.user.id, variant, Date.now()).run()

    return { variant }
  }
)

// Trigger when user completes activation milestone
export const checkActivation = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const user = await context.env.DB.prepare(`
      SELECT onboarding_step, subscription_status
      FROM users WHERE id = ?
    `).bind(context.user.id).first()

    if (user.onboarding_step === 'complete' && !user.subscription_status) {
      // User is activated but not subscribed → show upgrade prompt
      return {
        showUpgrade: true,
        timing: 'post_activation',
      }
    }
  }
)

export const getPersonalizedOnboarding = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const utmData = await context.env.DB.prepare(`
      SELECT utm_source, utm_campaign, utm_content
      FROM utm_clicks
      WHERE user_id = ?
      ORDER BY created_at DESC
      LIMIT 1
    `).bind(context.user.id).first()

    // Different onboarding for different sources
    if (utmData?.utm_campaign === "feature_stripe") {
      return { template: "stripe_focused_onboarding" }
    }

    return { template: "default_onboarding" }
  }
)