---

name: next-js-better-auth-integration category: Authentication author: Claude version: 1.0.0 tags: [nextjs, better-auth, authentication, app-router, sessions] description: A conceptual skill for integrating Better Auth with Next.js App Router

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