For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/web/onboarding.md (or send Accept: text/markdown).
Onboarding flow
The gated path from sign-up to an active workspace and plan.
Before you begin
Open your downloaded supastack project in Visual Studio Code using File → Open Folder, then choose Terminal → New Terminal. The repository root is the folder containing package.json, apps and packages. Run the command below there and leave its terminal open. If a command is not recognized, finish the tool installation guide before continuing.
Read the platform tutorial first. A server is the app process that answers browser or phone requests. Web reads apps/web/.env.local, Expo reads apps/mobile/.env.local, and database migration commands read root .env. The no-database /dashboard demonstration is separate from real /auth accounts, which need migrated Postgres. A phone or desktop-only checkout needs a separately running Web backend.
- Install the tools and get the code
- Learn commands, files and configuration
- Complete the Web first-run tutorial
corepack pnpm --filter @supastack/web devSetup and configuration
After sign-up, onboarding gates push the user through workspace setup before product work: /onboarding, /new-organization, /select-organization, and /choose-plan. The organization-onboarding module decides which step applies from the member's current state.
The flow is resumable — every gate re-derives the correct step server-side, so a user who leaves mid-way lands on the right screen when they return.
/onboarding entry gate
/new-organization create a team workspace
/select-organization pick an existing one
/choose-plan plan selection before billing
/invite/[token] invited members join hereImplementation workflow
Treat each step as a gate, not a wizard page — the server evaluates state and redirects to the next required step. Invited members skip creation and land on accept-invite instead.
When adding a product gate — a required profile field, a terms acknowledgement — extend the onboarding evaluation rather than scattering redirects through layouts.
Verification and troubleshooting
Test a fresh account through every step, a returning user mid-flow, an invited member, and a member of multiple organizations. Verify no step renders the app shell before its gate passes.