JWT Decode TypeScript: Type-Safe Token Handling with Examples

Sun, 28 Jun 2026 15:23:03 +0000

JWT Decode TypeScript is a library that allows you to decode JSON Web Tokens (JWT) in a type-safe manner using TypeScript. This ensures that the data extracted from the token is correctly typed, reducing runtime errors and improving code reliability.

What is JWT Decode TypeScript?

JWT Decode TypeScript is a lightweight library that provides a simple interface to decode JWTs. It leverages TypeScript’s type system to ensure that the decoded payload is correctly typed, which helps catch errors at compile time rather than at runtime.

How do you install JWT Decode TypeScript?

To start using JWT Decode TypeScript, you need to install the jwt-decode package via npm or yarn. Here’s how you can do it:

npm install jwt-decode
# or
yarn add jwt-decode

How do you decode a JWT using JWT Decode TypeScript?

Once you have installed the jwt-decode package, you can import it and use the decode function to parse JWT tokens. Let’s walk through a basic example.

Basic Example

Here’s a simple example of how to decode a JWT token:

import decode from 'jwt-decode';

// Example JWT token
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

// Define the structure of the token payload
interface TokenPayload {
  sub: string;
  name: string;
  iat: number;
}

// Decode the token
const decodedToken: TokenPayload = decode<TokenPayload>(token);

console.log(decodedToken);
// Output: { sub: '1234567890', name: 'John Doe', iat: 1516239022 }

Decoding Without Type Safety

If you decode a token without specifying the type, you lose the benefits of TypeScript’s type safety:

import decode from 'jwt-decode';

const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

// Decode the token without specifying the type
const decodedToken = decode(token);

console.log(decodedToken);
// Output: { sub: '1234567890', name: 'John Doe', iat: 1516239022 }

In the above example, decodedToken is of type any, which means you won’t get any type checking or autocompletion from TypeScript.

How do you handle errors when decoding JWTs?

When decoding JWTs, you should handle potential errors gracefully. Common issues include invalid tokens or malformed payloads. Here’s how you can handle these cases:

Error Handling Example

import decode from 'jwt-decode';

const token = 'invalid-token';

try {
  const decodedToken: TokenPayload = decode<TokenPayload>(token);
  console.log(decodedToken);
} catch (error) {
  console.error('Failed to decode token:', error);
  // Handle the error appropriately
}

In this example, if the token is invalid, the decode function will throw an error, which you can catch and handle accordingly.

What are the security considerations for JWT Decode TypeScript?

Ensuring the security of JWTs is crucial to protect your application from unauthorized access and tampering. Here are some key security considerations:

Verify the Token Signature

Always verify the signature of the JWT to ensure it hasn’t been tampered with. You can use libraries like jsonwebtoken to verify the signature.

import jwt from 'jsonwebtoken';
import decode from 'jwt-decode';

const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';
const secret = 'your-256-bit-secret';

try {
  const decodedToken = jwt.verify(token, secret) as TokenPayload;
  console.log(decodedToken);
} catch (error) {
  console.error('Failed to verify token:', error);
}

Validate the Token Expiry

Check the expiration time (exp) of the token to ensure it hasn’t expired.

import decode from 'jwt-decode';

const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE1MTYyMzk2MjJ9.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o';
const decodedToken: TokenPayload = decode<TokenPayload>(token);

if (decodedToken.exp && Date.now() >= decodedToken.exp * 1000) {
  console.error('Token has expired');
} else {
  console.log('Token is valid');
}

Avoid Storing Sensitive Information in Tokens

Do not store sensitive information like passwords or credit card details in JWTs. Only include necessary claims that are safe to expose.

How do you handle different token types?

JWTs can come in different types, such as access tokens and refresh tokens. Each type may have different structures and purposes. Here’s how you can handle different token types:

Example: Handling Access and Refresh Tokens

import decode from 'jwt-decode';

interface AccessTokenPayload {
  sub: string;
  name: string;
  iat: number;
  exp: number;
}

interface RefreshTokenPayload {
  sub: string;
  iat: number;
  exp: number;
}

const accessToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE1MTYyMzk2MjJ9.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o';
const refreshToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE2NDc3NzUwMjJ9.C4QzXrZpR2qKxV4eCZvRJdR8J2L8K2QJ2ZvRJdR8J2L';

const decodedAccessToken: AccessTokenPayload = decode<AccessTokenPayload>(accessToken);
const decodedRefreshToken: RefreshTokenPayload = decode<RefreshTokenPayload>(refreshToken);

console.log(decodedAccessToken);
console.log(decodedRefreshToken);

In this example, we define separate interfaces for access and refresh tokens to ensure that each token type is handled correctly.

How do you implement token refresh logic?

Token refresh logic is essential for maintaining user sessions without requiring re-authentication. Here’s a basic example of how you can implement token refresh logic using JWT Decode TypeScript:

Token Refresh Example

import decode from 'jwt-decode';
import axios from 'axios';

interface AccessTokenPayload {
  sub: string;
  name: string;
  iat: number;
  exp: number;
}

interface RefreshTokenPayload {
  sub: string;
  iat: number;
  exp: number;
}

const accessToken = localStorage.getItem('accessToken') || '';
const refreshToken = localStorage.getItem('refreshToken') || '';

const decodedAccessToken: AccessTokenPayload = decode<AccessTokenPayload>(accessToken);

if (decodedAccessToken.exp && Date.now() >= decodedAccessToken.exp * 1000) {
  // Access token has expired, refresh it
  try {
    const response = await axios.post('/api/refresh-token', { refreshToken });
    const newAccessToken = response.data.accessToken;
    localStorage.setItem('accessToken', newAccessToken);
    console.log('Access token refreshed');
  } catch (error) {
    console.error('Failed to refresh token:', error);
    // Handle the error appropriately, e.g., redirect to login page
  }
} else {
  console.log('Access token is still valid');
}

In this example, we check if the access token has expired. If it has, we send a request to the server to refresh the token and update the local storage with the new access token.

How do you handle token revocation?

Token revocation is an important aspect of managing user sessions. Here’s how you can handle token revocation using JWT Decode TypeScript:

Token Revocation Example

One common approach to token revocation is to maintain a list of revoked tokens on the server. When a token is revoked, you can check this list before processing requests.

import decode from 'jwt-decode';
import axios from 'axios';

interface AccessTokenPayload {
  sub: string;
  name: string;
  iat: number;
  exp: number;
}

const accessToken = localStorage.getItem('accessToken') || '';
const decodedAccessToken: AccessTokenPayload = decode<AccessTokenPayload>(accessToken);

try {
  const response = await axios.post('/api/validate-token', { token: accessToken });
  const isValid = response.data.isValid;

  if (isValid) {
    console.log('Token is valid');
    // Proceed with the request
  } else {
    console.error('Token is revoked');
    // Handle the error appropriately, e.g., redirect to login page
  }
} catch (error) {
  console.error('Failed to validate token:', error);
}

In this example, we send a request to the server to validate the token. The server checks if the token is in the list of revoked tokens and returns a response indicating whether the token is valid.

How do you test JWT Decode TypeScript?

Testing is crucial to ensure that your token handling logic works as expected. Here’s how you can write tests for JWT Decode TypeScript using Jest:

Testing Example

First, install Jest if you haven’t already:

npm install --save-dev jest @types/jest ts-jest

Then, create a test file, e.g., token.test.ts:

import decode from 'jwt-decode';

interface TokenPayload {
  sub: string;
  name: string;
  iat: number;
  exp: number;
}

describe('JWT Decode', () => {
  it('should decode a valid token', () => {
    const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE2NDc3NzUwMjJ9.C4QzXrZpR2qKxV4eCZvRJdR8J2L8K2QJ2ZvRJdR8J2L';
    const decodedToken: TokenPayload = decode<TokenPayload>(token);

    expect(decodedToken.sub).toBe('1234567890');
    expect(decodedToken.name).toBe('John Doe');
    expect(decodedToken.iat).toBe(1516239022);
    expect(decodedToken.exp).toBe(1647775022);
  });

  it('should throw an error for an invalid token', () => {
    const token = 'invalid-token';

    expect(() => decode<TokenPayload>(token)).toThrow();
  });
});

In this example, we write two tests: one to verify that a valid token is decoded correctly and another to ensure that an invalid token throws an error.

Quick Answer

JWT Decode TypeScript is a library that allows you to decode JSON Web Tokens in a type-safe manner using TypeScript. It provides a simple interface to parse JWTs and leverages TypeScript’s type system to ensure that the decoded payload is correctly typed.

Key Takeaways

Use JWT Decode TypeScript to decode JWTs in a type-safe manner.
Always verify the signature of the JWT to ensure it hasn’t been tampered with.
Check the expiration time of the token to ensure it hasn’t expired.
Avoid storing sensitive information in JWTs.
Implement token refresh logic to maintain user sessions without requiring re-authentication.
Handle token revocation to manage user sessions effectively.
Test your token handling logic to ensure it works as expected.

That’s it. Simple, secure, works. Happy coding!

Token-Handling on IAMDevBox