🔐 jwtdecodemaster

A lightweight, zero-dependency JWT decoder for Node.js and browsers. Decode JWT tokens without verification - perfect for extracting header and payload data from JSON Web Tokens.

✨ Features

• 🚀 Zero dependencies - No external packages required
• 🌐 Universal - Works in both Node.js and browsers
• 📦 Lightweight - Minimal bundle size
• 💪 TypeScript - Full TypeScript support with type definitions
• ✅ Robust - Comprehensive error handling and validation
• 🔒 Safe - Validates JWT format before decoding

📦 Installation

npm install jwtdecodemaster

yarn add jwtdecodemaster

pnpm add jwtdecodemaster

🚀 Usage

Basic Example

import { decodeJWT } from 'jwtdecodemaster';

const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

try {
  const decoded = decodeJWT(token);

  console.log('Header:', decoded.header);
  // Output: { alg: 'HS256', typ: 'JWT' }

  console.log('Payload:', decoded.payload);
  // Output: { sub: '1234567890', name: 'John Doe', iat: 1516239022 }
} catch (error) {
  console.error('Failed to decode JWT:', error.message);
}

CommonJS

const { decodeJWT } = require('jwtdecodemaster');

const token = 'your.jwt.token';
const decoded = decodeJWT(token);

console.log(decoded.header);
console.log(decoded.payload);

Browser (ES Modules)

<script type="module">
  import { decodeJWT } from './node_modules/jwtdecodemaster/dist/index.js';

  const token = 'your.jwt.token';
  const decoded = decodeJWT(token);

  console.log(decoded);
</script>

📖 API

decodeJWT(token: string): DecodedJWT

Decodes a JWT token and returns the header and payload.

Parameters

• token (string): The JWT token to decode

Returns

interface DecodedJWT {
  header: Record<string, any>;
  payload: Record<string, any>;
}

Throws

• Error if the token is invalid or cannot be decoded

Examples

// Valid token
const result = decodeJWT('eyJhbGci...');
// Returns: { header: {...}, payload: {...} }

// Invalid token - throws error
decodeJWT('invalid.token');
// Throws: Error('Invalid JWT token: token must have 3 parts separated by dots')

// Empty token - throws error
decodeJWT('');
// Throws: Error('Invalid JWT token: token must be a non-empty string')

⚠️ Important Notes

This library does NOT verify tokens

jwtdecodemaster only decodes JWT tokens - it does NOT verify signatures or validate tokens. This means:

• ❌ Does not check if the token is signed correctly
• ❌ Does not validate expiration (exp claim)
• ❌ Does not verify issuer (iss claim)
• ✅ Only extracts and decodes header and payload data

Use this library only when you need to read token data without verification (e.g., client-side token inspection, debugging, logging).

For token verification, use libraries like:

• jsonwebtoken (Node.js)
• jose (Universal)

🔧 Error Handling

The library provides detailed error messages for different failure scenarios:

try {
  const decoded = decodeJWT(token);
} catch (error) {
  // Possible error messages:
  // - "Invalid JWT token: token must be a non-empty string"
  // - "Invalid JWT token: token must have 3 parts separated by dots"
  // - "Invalid JWT token: all parts must be non-empty"
  // - "JWT part cannot be empty"
  // - "Base64 decode failed: ..."
  // - "Failed to decode JWT token: ..."
}

🌍 Browser Compatibility

Works in all modern browsers that support:

• ES2020
• atob() or TextDecoder
• Uint8Array

Tested in:

• ✅ Chrome/Edge (latest)
• ✅ Firefox (latest)
• ✅ Safari (latest)
• ✅ Node.js 14+

📝 License

MIT © Cavid Salimov

🤝 Contributing

Contributions, issues, and feature requests are welcome!

📧 Support

If you have any questions or need help, please open an issue on GitHub.