Documentation

Authentication

StartupKit ships with email + password auth, Google OAuth, email verification, password reset, onboarding, and middleware-based route protection powered by NextAuth.js.

Architecture Overview

  • NextAuth configuration: src/lib/auth.ts wires the Prisma adapter, Google provider and Credentials provider.
  • Database models: Defined in prisma/schema.prisma (User, Account, Session, VerificationToken, PasswordResetToken).
  • UI flows: All auth pages live in src/app/(auth) and use shadcn/ui components for consistency.
  • Middleware: src/middleware.ts guards dashboard routes, onboarding, and optional subscription enforcement.

Flows

Registration

  1. User signs up at /register with email/password or Google.
  2. Email/password users receive a verification link (Resend or console log).
  3. Google users have emailVerified set automatically.
  4. Everyone is redirected to /dashboard/onboarding until they finish the profile form.

Login

Credentials are validated with bcrypt via Prisma. Users must have emailVerified set. OAuth users can log in immediately after the Google callback.

Password Reset

  1. Users request a reset at /forgot-password.
  2. A PasswordResetToken is created and emailed (or logged in dev).
  3. The reset page verifies the token and lets the user set a new password.

Configuration Steps

  1. Fill out the env vars in .env (DATABASE_URL, NEXTAUTH_SECRET, Google, Resend, etc.).
  2. Generate Prisma client + push schema.
  3. Start the dev server and register your first account.
  4. Visit /dev-tools to mark the account verified if you have not hooked up Resend yet.

Extending Authentication

  • Add providers: Import any NextAuth provider inside src/lib/auth.ts and append it to the providers array. Remember to set env vars for the provider keys.
  • Custom fields: Add columns to the User model in Prisma, runnpx prisma db push, then update onboarding + dashboard forms to collect/store values.
  • Session data: Use the jwt and session callbacks to expose extra fields to the client.

Testing Checklist

  • Create two accounts: email/password and Google.
  • Ensure the middleware forces onboarding before hitting /dashboard.
  • Confirm the password reset email logs the correct URL locally.
  • Toggle ENABLE_SUBSCRIPTION_ENFORCEMENT to verify gated dashboards still respect auth.