Type-safe authentication in Next.js: a complete guide with NextAuth.js v5

Why type-safe authentication matters

Type safety in authentication isn't just about catching typos—it's about preventing security vulnerabilities and runtime errors that could compromise user data. With TypeScript and NextAuth.js v5, Fastack ensures that:

• Session data is type-safe across your entire application
• API routes have validated request/response types
• User data is properly typed in components and hooks
• Authentication errors are caught at compile time

What you get with Fastack

Fastack includes a complete @saas/auth package that provides:

Multiple authentication methods

• Email/Password Authentication - Secure credential-based login with bcrypt hashing
• Google OAuth - One-click sign-in with Google accounts
• GitHub OAuth - Developer-friendly GitHub authentication
• Automatic Account Linking - OAuth accounts automatically link to existing email accounts

Email verification system

Fastack includes a comprehensive email verification system with multiple verification methods:

• Magic Link Verification - Click-to-verify email links
• OTP (One-Time Password) - 6-digit code verification
• Resend Verification - Users can request new verification emails
• Email Change Verification - Secure email address updates

Password management

• Secure Password Hashing - bcrypt with 12 salt rounds
• Password Reset Flow - Secure token-based password reset
• Password Change - Update password with current password verification
• Forgot Password - Email-based password recovery

Account management

• Profile Updates - Update name and user details
• Account Deletion - Secure account removal with confirmation
• Session Management - JWT-based sessions via NextAuth.js

Type-safe session management

Fastack extends NextAuth.js types to provide full type safety for your session data. Here's how it works:

import 'next-auth';
import { DefaultSession } from 'next-auth';

declare module 'next-auth' {
  interface Session {
    user: {
      id: string;
      role?: string;
      emailVerified?: Date | null;
    } & DefaultSession['user'];
  }

  interface User {
    role?: string;
    emailVerified?: Date | null;
  }
}

This ensures that when you access session.user in your components, TypeScript knows exactly what properties are available.

OAuth integration: Google & GitHub

Setting up OAuth providers typically takes hours of configuration and testing. Fastack includes pre-configured OAuth providers that work out of the box:

import GoogleProvider from 'next-auth/providers/google';
import GitHubProvider from 'next-auth/providers/github';

export const authConfig: NextAuthOptions = {
  providers: [
    GoogleProvider({
      clientId: process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
    GitHubProvider({
      clientId: process.env.NEXT_PUBLIC_GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }),
    // ... credentials provider
  ],
  // ... rest of config
};

The configuration includes intelligent account linking—if a user signs up with email/password and later tries to sign in with Google using the same email, the accounts are automatically linked.

Email verification flow

Fastack implements a dual-verification system that sends both a magic link and an OTP code, giving users flexibility in how they verify their email:

// 1. User registers
const user = await prisma.user.create({
  data: { email, password: hashedPassword }
});

// 2. Generate verification token and OTP
const verificationToken = crypto.randomBytes(32).toString('hex');
const otpCode = Math.floor(100000 + Math.random() * 900000).toString();

// 3. Store verification data
await prisma.verificationToken.create({
  data: {
    identifier: email,
    token: verificationToken,
    otp: otpCode,
    expires: new Date(Date.now() + 86400000), // 24 hours
  },
});

// 4. Send verification email with both methods
await sendEmailVerificationEmail(email, verificationToken, {
  otpCode,
  expiresIn: '24 hours',
});

Users can verify their email either by clicking the magic link or entering the 6-digit OTP code, providing a better user experience.

Pre-built React hooks

Fastack provides type-safe React hooks for all authentication operations, making it easy to integrate auth into your components:

import { useSignIn, useSignUp, useForgotPassword } from '@saas/auth';

function SignInForm() {
  const signIn = useSignIn({
    onSuccess: () => router.push('/dashboard'),
    onError: (error) => console.error(error),
  });

  const handleSubmit = async (data: SignInInput) => {
    await signIn.mutateAsync(data);
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* Form fields */}
    </form>
  );
}

All hooks are built on TanStack Query, providing loading states, error handling, and optimistic updates out of the box.

Security features

Security is built into every aspect of Fastack's authentication system:

• CAPTCHA Protection - Cloudflare Turnstile integration prevents bot sign-ups
• Rate Limiting - Built-in protection against brute force attacks
• Secure Token Generation - Cryptographically secure random tokens
• Password Strength Validation - Zod schemas ensure strong passwords
• Email Verification Required - New accounts must verify email before full access

Pre-built UI components

Fastack includes complete, production-ready UI components for all authentication flows:

• Sign in page with email/password and OAuth buttons
• Sign up page with email verification
• Email verification page with OTP input
• Forgot password and reset password pages
• Account settings with profile updates

All components are fully typed, accessible, and styled with HeroUI v3 for a modern, professional look.

Time saved: 30+ hours

Building authentication from scratch typically requires:

• Setting up NextAuth.js configuration (4-6 hours)
• Implementing OAuth providers (6-8 hours)
• Building email verification system (4-6 hours)
• Creating password reset flow (3-4 hours)
• Building UI components (6-8 hours)
• Writing type definitions (2-3 hours)
• Testing and debugging (5-8 hours)

Total: 30-43 hours of development time that you save with Fastack.

Conclusion

Type-safe authentication is essential for building secure, maintainable SaaS applications. Fastack provides a complete, production-ready authentication system that saves you weeks of development time while ensuring security and type safety throughout your application.

With Fastack, you get:

• Complete type-safe authentication system
• OAuth providers (Google, GitHub) pre-configured
• Email verification with magic links and OTP
• Password management (reset, change, forgot)
• Pre-built UI components and React hooks
• Security features (CAPTCHA, rate limiting, secure tokens)