Authentication Guide

JWT Auth Token Strategies

Choose how your application stores authentication tokens. Each strategy has different security and persistence characteristics.

Cookie-Based

Both tokens in HttpOnly cookies

RECOMMENDED⭐⭐⭐⭐⭐

The recommended approach for production apps. Both access and refresh tokens are stored in HttpOnly cookies, making them invisible to JavaScript and protected from XSS attacks.

XSS-proofCSRF protectionSSR compatibleAuto-sent

Read the guide

Memory + Cookie

Access in memory, refresh in cookie

⭐⭐⭐⭐

Access token stored in React state (lost on page refresh), refresh token in HttpOnly cookie. Good balance between security and flexibility.

Refresh XSS-proofToken in JSAuto-refreshSPAs

Read the guide

LocalStorage

Both tokens in localStorage

⭐⭐

Simple but less secure. Both tokens stored in localStorage, accessible to JavaScript. Only recommended for prototypes or low-risk applications.

PersistentSimple APICross-tabEasy debug

Read the guide

SessionStorage

Both tokens in sessionStorage

⭐⭐

Similar to localStorage but clears when tab/browser closes. Slightly better security due to tab isolation.

Tab isolatedAuto-clearSimple APISession only

Read the guide

Strategy Comparison

Feature	Cookie-Based	Memory+Cookie	LocalStorage	SessionStorage
XSS Protection	✅ Full	✅ Refresh safe	❌ None	❌ None
Persists Access Token	✅ Yes	❌ No	✅ Yes	❌ No
Persists Refresh Token	✅ Yes	✅ Yes	✅ Yes	❌ No
Cross-Tab Support	✅ Yes	❌ No	✅ Yes	❌ No
SSR Compatible	✅ Yes	⚠️ Extra work	⚠️ Extra work	⚠️ Extra work
Implementation	Low	Medium	Low	Low
Client Token Access	❌ No	✅ Yes	✅ Yes	✅ Yes

Backend API Endpoints

The JWT auth frontend works with any backend (Node.js, Python, Go, etc.). Your backend should implement these endpoints:

Method	Endpoint	Description
POST	/auth/register	Create new account
POST	/auth/login	Sign in with credentials
POST	/auth/logout	Sign out (clear tokens)
POST	/auth/refresh	Get new access token
GET	/auth/me	Get current user
POST	/auth/forgot-password	Send reset email
POST	/auth/reset-password	Reset with token
POST	/auth/change-password	Change password
GET	/auth/profile	Get profile
PUT	/auth/profile	Update profile
DELETE	/auth/profile	Delete account

Quick Start

1. Scaffold with JWT Auth

$ npx nexstruct

? Select authentication:
  ◉ JWT Auth (Custom)

? Select token strategy:
  ◉ Cookie-Based (Recommended)

2. Configure environment

# .env.local
NEXT_PUBLIC_API_URL=http://localhost:3001
ACCESS_TOKEN_SECRET=your-secret-min-32-chars
REFRESH_TOKEN_SECRET=your-secret-min-32-chars

3. Start development

$ cd my-app
$ npm install
$ npm run dev

Loading…