next-js-better-auth-integration

name	next-js-better-auth-integration
description	Use when working with a conceptual skill for integrating Better Auth with Next.js App Router
metadata	{"author":"ForceInjection"}

Next.js Better Auth Integration Skill

When to Use This Skill

Use this conceptual skill when you need to implement authentication in a Next.js application using the App Router architecture with Better Auth. This skill is appropriate for:

• Adding user authentication to Next.js applications
• Implementing secure session management with Better Auth
• Enabling JWT-based authentication flows
• Creating protected routes and pages in Next.js
• Managing user sessions across the application
• Implementing social login capabilities

This skill should NOT be used for:

• Applications using the Pages Router (use _app.js instead)
• Applications that don't require user authentication
• Simple static sites without user interaction
• Applications with custom authentication requirements that conflict with Better Auth

Prerequisites

• Next.js 13+ with App Router enabled
• Better Auth package installed and configured
• Understanding of Next.js middleware and server components
• Knowledge of authentication concepts and session management
• Environment for managing authentication secrets securely

Conceptual Implementation Framework

Better Auth Initialization Capability

• Configure Better Auth with appropriate providers and settings
• Set up authentication database or adapter configuration
• Define user model and authentication options
• Initialize authentication client for frontend usage
• Configure authentication callbacks and customizations

JWT Token Enablement Capability

• Configure JWT token generation and validation settings
• Set token expiration and refresh mechanisms
• Define token payload structure and claims
• Enable secure token storage and transmission
• Configure token signing and verification algorithms

App Wrapping for Session Management Capability

• Wrap the Next.js application with Better Auth provider
• Configure session context for client components
• Set up server-side session access in server components
• Establish session persistence across application routes
• Enable session synchronization between client and server

Hook Usage Capability

• Provide access to authentication state via hooks
• Enable user session data retrieval in components
• Support authentication status checking in real-time
• Allow for custom authentication flows and callbacks
• Enable logout and session management functionality

Protected Route Implementation Capability

• Create middleware for protecting application routes
• Implement server-side authentication checks
• Enable client-side session verification
• Handle unauthorized access scenarios appropriately
• Redirect users based on authentication status

Expected Input/Output

Input Requirements:

1. Better Auth Configuration:

   • Database connection settings
   • Authentication providers configuration
   • JWT settings and secrets
   • Customization options for UI and behavior
   • Callback URLs and redirect settings

2. Next.js App Structure:

   • App Router directory structure (/app)
   • Middleware configuration (middleware.ts)
   • Layout files that need authentication context
   • Pages requiring authentication protection

Output Formats:

1. Initialized Authentication System:

   • Configured Better Auth instance
   • Ready-to-use authentication context
   • Properly set up session management
   • Working JWT token system

2. Authenticated Component State:

   • User session data available in components
   • Authentication status (logged in/out)
   • User profile information when authenticated
   • Session tokens and refresh mechanisms

3. Protected Route Responses:

   • HTTP 200 OK for authenticated users
   • HTTP 302/307 redirects for unauthenticated users
   • Proper error handling for authentication failures
   • Consistent session state across the application

4. Hook Results:

   • User authentication status
   • Session data when available
   • Loading states during authentication checks
   • Error states for authentication failures

Integration Patterns

App Router Integration

• Configure root layout to provide authentication context
• Implement middleware for route protection
• Use server components for server-side session access
• Leverage client components for interactive authentication UI

Session Management

• Server-side session handling in server components
• Client-side session synchronization in client components
• Cross-component session state consistency
• Proper session cleanup and invalidation

Authentication Flows

• Sign-in and sign-up process management
• Social authentication provider integration
• Password reset and account recovery
• Multi-factor authentication (if supported)

Security Considerations

1. Token Security: Secure JWT token storage and transmission
2. Session Management: Proper session invalidation and refresh
3. CSRF Protection: Implement CSRF protection for forms
4. Secure Cookies: Use secure, HTTP-only cookies for sessions
5. Input Validation: Validate all authentication inputs
6. Rate Limiting: Implement rate limiting for authentication endpoints
7. Secret Management: Securely store authentication secrets

Performance Implications

• Optimize session lookup performance in middleware
• Consider caching strategies for session data
• Minimize authentication overhead on each request
• Efficient token validation mechanisms
• Lazy loading of authentication context when possible

Error Handling and Validation

• Handle authentication initialization failures
• Manage session expiration scenarios
• Provide appropriate feedback for failed authentication
• Validate authentication state consistency
• Handle network failures during authentication checks

Testing Considerations

• Test authentication flow in server components
• Verify session persistence across requests
• Validate protected route access controls
• Test JWT token generation and validation
• Verify social login provider integration
• Test authentication edge cases and error states

---

Source: ForceInjection/domain-driven-design-skills — distributed by TomeVault.