JWT Handling in JavaScript: jsonwebtoken vs jwt-decode vs jwt-simple

Working with JSON Web Tokens (JWTs) requires understanding what operations you actually need: signing, verifying, or just reading token contents. Each package serves different purposes, and choosing the wrong one can lead to serious security issues or unnecessary bloat. Let’s compare them based on real engineering needs.

🔐 Core Capabilities: What Each Package Actually Does

jsonwebtoken: Full Signing and Verification (Server-Side)

This is the industry-standard library for creating and validating JWTs in Node.js. It handles cryptographic signing, algorithm enforcement, and expiration checks properly.

// Signing a token (Node.js only)
const jwt = require('jsonwebtoken');
const token = jwt.sign({ userId: 123 }, 'secret', { expiresIn: '1h' });

// Verifying a token securely
try {
  const decoded = jwt.verify(token, 'secret');
  console.log(decoded.userId); // 123
} catch (err) {
  // Handle invalid/expired tokens
}

Key point: It throws errors for expired tokens, invalid signatures, or algorithm mismatches — exactly what you want for security.

jwt-decode: Payload Inspection Only (Client-Side)

This package does one thing: parse the base64-encoded payload of a JWT. It performs zero cryptographic verification.

// Decoding a token in the browser
import jwtDecode from 'jwt-decode';

const token = 'eyJ...'; // From localStorage or cookies
const payload = jwtDecode(token);
console.log(payload.exp); // Expiration timestamp

// Check if token is expired (manual check)
if (payload.exp * 1000 < Date.now()) {
  // Token expired
}

Use case: Showing user info from a token your backend already validated, or checking expiration before making API calls.

jwt-simple: Basic Encoding/Decoding (Not Recommended)

This package provides minimal JWT functionality but has dangerous defaults. It doesn’t validate algorithms during decode, opening doors to security flaws.

// Encoding (works)
const jwt = require('jwt-simple');
const token = jwt.encode({ userId: 123 }, 'secret');

// Decoding (dangerous!)
const payload = jwt.decode(token, 'secret');
// No error thrown for expired tokens or wrong algorithms

Critical issue: If an attacker changes the algorithm header to none, jwt-simple will accept unsigned tokens unless you manually add checks — which most developers forget to do.

⚠️ Security Implications: Where Things Go Wrong

Algorithm Confusion Attacks

The biggest JWT vulnerability happens when libraries don’t enforce expected algorithms. Here’s how each package handles it:

• jsonwebtoken: Forces you to specify allowed algorithms. Rejects tokens with unexpected algorithms by default.

  // Safe: Only allows HS256
  jwt.verify(token, secret, { algorithms: ['HS256'] });
  

• jwt-decode: Doesn’t verify signatures at all — so this attack isn’t relevant (but also means it can’t protect you).

• jwt-simple: Accepts any algorithm, including none. An attacker could forge a token like:

  // Malicious token with "alg": "none"
  const forged = jwt.encode({ admin: true }, '', { algorithm: 'none' });
  jwt.decode(forged, 'real-secret'); // Returns { admin: true }!
  

Expiration Handling

• jsonwebtoken: Automatically checks exp claims during verify() and throws TokenExpiredError.
• jwt-decode: Returns raw payload — you must manually compare exp to current time.
• jwt-simple: Ignores exp entirely during decode — no automatic validation.

🌐 Environment Compatibility

* jwt-simple works in browsers but requires you to provide your own crypto implementation for signing — which most frontend apps shouldn’t be doing anyway.

🛠️ Real-World Usage Patterns

Typical Secure Flow (Recommended)

1. Backend (Node.js): Use jsonwebtoken to sign tokens during login

   // Server
   const token = jwt.sign({ id: user.id }, process.env.JWT_SECRET, { expiresIn: '15m' });
   

2. Frontend: Store token securely (httpOnly cookie or memory)

3. Frontend: Use jwt-decode only to read payload for UI decisions

   // Client
   const { exp } = jwtDecode(token);
   if (Date.now() >= exp * 1000) {
     // Redirect to login
   }
   

4. Backend: Always verify tokens with jsonwebtoken on protected routes

Anti-Pattern to Avoid

❌ Using jwt-simple for verification:

// NEVER do this
app.get('/profile', (req, res) => {
  const payload = jwtSimple.decode(req.headers.authorization, SECRET);
  // No expiration check, no algorithm validation!
  res.json(payload);
});

✅ Correct approach with jsonwebtoken:

app.get('/profile', (req, res) => {
  try {
    const payload = jwt.verify(req.headers.authorization, SECRET);
    res.json(payload);
  } catch (err) {
    res.status(401).json({ error: 'Invalid token' });
  }
});

📦 Bundle Size Considerations

While exact numbers aren’t provided per instructions, the practical impact is clear:

• jwt-decode: Adds ~500 bytes — negligible for any app
• jsonwebtoken: Adds significant weight (pulls in Node crypto polyfills if forced into browser bundles)
• jwt-simple: Small, but false economy due to security risks

If you’re tempted to use jsonwebtoken in the browser just to verify tokens — don’t. Offload verification to your backend API where it belongs.

🚫 Deprecation and Maintenance Status

• jsonwebtoken: Actively maintained, widely adopted in the Node.js ecosystem
• jwt-decode: Actively maintained, focused scope ensures longevity
• jwt-simple: Not recommended for new projects. Last meaningful update was years ago, and the README includes warnings about security limitations

💡 Decision Checklist

Ask yourself these questions:

1. Do I need to create or verify JWT signatures?

   • Yes → Use jsonwebtoken (Node.js only)
   • No → Skip to next question

2. Am I in a browser environment just reading token contents?

   • Yes → Use jwt-decode
   • No → You probably need jsonwebtoken

3. Is this a new project?

   • Yes → Never choose jwt-simple
   • Existing jwt-simple usage → Plan migration to jsonwebtoken

📊 Summary Table

🔚 Final Guidance

• For Node.js servers: jsonwebtoken is the clear, secure choice for all JWT operations.
• For browser clients: jwt-decode is perfect for non-cryptographic token inspection.
• Avoid jwt-simple entirely — the minor convenience isn’t worth the security debt.

Remember: JWT verification should almost always happen on the server. Your frontend’s job is usually just to store the token and send it with requests — not to decide if it’s valid.