Add a new onboarding step

The onboarding flow in supastarter is designed to be modular and easily extensible. This guide explains how to add new steps to the onboarding process.

Overview

The onboarding system consists of two main components:

• OnboardingForm.vue - The container component that manages step navigation
• Individual step components (e.g., OnboardingStep1.vue)

Adding a New Step

1. Create the Step Component

Create a new file for your step component in apps/saas/modules/onboarding/components/. For example, OnboardingStep2.vue:

<script setup lang="ts">
import { z } from "zod";

const emit = defineEmits<{
  complete: [];
}>();

const { t } = useTranslations();

const formSchema = z.object({
  // Add your form fields here
});

type FormValues = z.infer<typeof formSchema>;

const onSubmit = async (event: FormSubmitEvent<FormValues>) => {
  try {
    // Handle form submission
    // Update user data if needed
    emit("complete");
  } catch (e) {
    // Handle error
  }
};
</script>

<template>
  <UForm :schema="formSchema" @submit="onSubmit">
    <!-- Add your form fields here -->
    <UButton type="submit">
      {{ t("onboarding.continue") }}
    </UButton>
  </UForm>
</template>

2. Update OnboardingForm.vue

Add your new step to the steps array in OnboardingForm.vue.

3. Add Translations

Add the necessary translations for your step in your translation files under packages/i18n/translations/en/saas.json:

{
  "onboarding": {
    "step2": {
      "title": "Step 2 Title",
      "description": "Step 2 Description"
    }
  }
}

Best Practices

1. State Management: Use the complete emit to handle navigation between steps. For the final step, call the main completion function to finish onboarding.

2. Form Validation: Always use Zod schemas for form validation with proper error handling.

3. UI Components: Use Nuxt UI components for consistency.

4. Responsive Design: Ensure your step component works well on both mobile and desktop using Tailwind's responsive classes.

5. Progress Indicator: The progress bar will automatically update based on the number of steps in the steps array.

Notes

• The onboarding state is tracked in the URL using the step query parameter
• The final completion function updates the user's onboardingComplete status and redirects to the app
• Each step component uses Vue's Composition API with <script setup>