Configure Auth
Authentication in Fast Unicorn is built on NextAuth v5 with Prisma and JWT sessions.
This guide explains where the authentication system lives, which variables it needs, and how the current flows are organized so you can extend them without breaking route or service boundaries.
Before configuring auth
Finish the local setup from Installation and make sure your environment values are ready in Environment before testing providers or recovery flows.
What this guide covers
Provider setup
How the current auth providers are wired and which environment values they depend on.
User flows
How sign-in, sign-up, and password recovery are split across routes, routers, and services.
Extension points
Where to add new auth behavior while keeping the current project structure clean.
Main files and folders
| File | Description |
|---|---|
src/server/auth/config.ts | Configure the auth providers. |
src/server/api/routers/customAuth.ts | Sign-up mutation. |
src/server/services/auth/password-recovery.ts | Password recovery service. |
src/app/[locale]/auth/signin | Sign-in page. |
src/app/[locale]/auth/signup | Sign-up page. |
src/app/[locale]/auth/forgot-password | Forgot password page. |
Current providers
The template currently enables:
- Google OAuth
- Credentials
Provider wiring lives in src/server/auth/config.ts.
Recommended auth sequence
Use this order when you start changing authentication behavior.
Prepare the required environment
Set auth, database, and provider credentials before testing any sign-in flow locally.
Review provider configuration
Confirm the provider setup in the auth config matches the flows you want to support.
Understand router and service boundaries
Keep transport logic and auth behavior in the tRPC router before adding new features.
Test every auth path
Verify sign-in, sign-up, recovery, redirects, and session shape before extending the system further.
Required environment variables
| Variable | Propósito |
|---|---|
AUTH_SECRET | Secret key for the auth system. |
GOOGLE_CLIENT_ID | Google OAuth client ID. |
GOOGLE_CLIENT_SECRET | Google OAuth client secret. |
DATABASE_URL | Database URL. |
See Environment if you need the broader variable reference or service setup notes.
Credentials flow
Credentials sign-in validates email and password with Zod, loads the user from Prisma, and verifies the stored hash with argon2.
Use this flow when you want native email/password authentication without relying only on OAuth.
Sign-up flow
The sign-up mutation lives in src/server/api/routers/customAuth.ts.
What the sign-up mutation does
- Validates the input
- Checks for an existing user
- Hashes the password
- Creates the user record
Password recovery flow
Password recovery logic lives in the customAuth.ts router procedures.
The recovery procedures in src/server/api/routers/customAuth.ts handle:
- Six-digit code generation
- 15-minute expiration window
- Resend throttling
- Code lookup and consumption
The same router sends the email and applies the password update after verification.
Project structure reminder
If you need to extend auth, keep route UI inside src/app, reusable auth UI in
src/features/auth/, and API logic in the tRPC router. That matches the guidance from
Project Structure.
Session shape
The app adds these fields to the session:
- user.id
- user.role
This makes it easier to protect routes and authorize actions across the app.
Extending auth
When adding more auth features:
- Keep provider setup in src/server/auth/config.ts
- Keep route-specific form behavior in src/app/[locale]/auth
- Keep reusable auth UI in src/features/auth/
- Keep API contracts (including recovery logic) in the tRPC router
That separation makes authentication easier to reason about now and much easier to extend later when you add more providers, onboarding logic, roles, or account recovery rules.