Frontend API Client with JWT Skill

When to Use This Skill

Use this conceptual skill when you need to implement a robust API client in Next.js that properly handles JWT tokens for authentication. This skill is appropriate for:

• Creating centralized API communication layer in Next.js applications
• Managing JWT-based authentication across multiple API endpoints
• Handling token expiration and refresh scenarios
• Standardizing error response parsing and handling
• Implementing secure API communication patterns

This skill should NOT be used for:

• Applications without JWT-based authentication
• Static sites without API communication needs
• Applications using alternative authentication methods (API keys, OAuth 2.0 client credentials, etc.)
• Simple applications with minimal API interaction

Prerequisites

• Next.js application (either App Router or Pages Router)
• Understanding of JWT (JSON Web Token) concepts
• Knowledge of HTTP headers and authorization mechanisms
• Basic understanding of asynchronous JavaScript operations
• Awareness of client-side vs server-side execution contexts

Conceptual Implementation Framework

Authorization Header Attachment Capability

• Automatically attach JWT tokens to API requests as Authorization headers
• Determine when to include tokens based on request type and endpoint
• Handle token attachment for both client-side and server-side requests
• Manage token inclusion in cross-origin requests appropriately
• Ensure proper header formatting ("Bearer <token>")

Token Expiry Handling Capability

• Detect JWT token expiration before making API requests
• Implement automatic token refresh mechanisms
• Handle token refresh failures gracefully
• Maintain session continuity during token refresh
• Coordinate token refresh across multiple concurrent requests
• Store updated tokens securely after refresh

Error Response Parsing Capability

• Parse structured error responses from API endpoints
• Identify authentication-related errors (401, 403) for special handling
• Extract meaningful error messages for user feedback
• Handle different error response formats consistently
• Distinguish between client errors, server errors, and network issues
• Provide appropriate user feedback based on error types

API Call Centralization Capability

• Create a unified interface for all API communications
• Standardize request and response handling across the application
• Implement consistent error handling and logging
• Manage request/response interceptors for cross-cutting concerns
• Provide type-safe API call patterns (when using TypeScript)
• Enable request caching and deduplication where appropriate

Expected Input/Output

Input Requirements:

1. JWT Token Management:

- Valid JWT token for authorization - Token refresh endpoint configuration - Token storage mechanism (localStorage, cookies, etc.) - Token expiration time and refresh timing

1. API Configuration:

- Base API URL for requests - Request timeout settings - Custom headers and request options - Endpoint-specific configurations

1. Request Parameters:

- HTTP method (GET, POST, PUT, DELETE, etc.) - Request URL or endpoint identifier - Request body for POST/PUT operations - Query parameters and path variables

Output Formats:

1. Successful API Response:

- HTTP 200-299 status codes - Parsed response data matching expected format - Updated token information when applicable - Consistent response structure across all endpoints

1. Authentication Error Response:

- HTTP 401 Unauthorized for expired/invalid tokens - Automatic token refresh attempt - Redirect to login page after refresh failure - Clear error messaging for authentication issues

1. Authorization Error Response:

- HTTP 403 Forbidden for insufficient permissions - Appropriate error handling based on permission level - User feedback for access restriction

1. General Error Response:

- Structured error object with message and code - Appropriate HTTP status code - Detailed error information for debugging - User-friendly error messages for UI display

Integration Patterns

Client-Side Integration

• Handle API calls from client components and client-side rendering
• Manage token storage and retrieval in browser context
• Implement request interceptors for header attachment
• Coordinate with authentication state management

Server-Side Integration (when applicable)

• Handle API calls from server components
• Manage token transmission securely between server and client
• Implement server-side token validation
• Handle server-side error responses appropriately

React Component Integration

• Provide hooks for API communication in functional components
• Enable context-based API client access
• Support both functional and class component patterns
• Implement proper cleanup and cancellation mechanisms

Security Considerations

1. Token Storage: Secure JWT token storage to prevent XSS attacks
2. Header Transmission: Use HTTPS for all API communications
3. Token Refresh: Implement secure token refresh mechanisms
4. Error Information: Avoid exposing sensitive information in error messages
5. Request Validation: Validate request parameters before sending
6. Response Validation: Verify response integrity and format
7. Cross-Site Requests: Implement proper CORS handling

Performance Implications

• Optimize token retrieval and attachment for minimal overhead
• Implement efficient token refresh to avoid blocking requests
• Consider request caching strategies for improved performance
• Minimize redundant API calls through proper state management
• Implement request batching where appropriate
• Monitor and optimize network request timing

Error Handling and Validation

• Validate JWT token format and expiration before requests
• Handle network connectivity issues gracefully
• Implement retry mechanisms for transient failures
• Provide fallback behaviors for critical API failures
• Log errors appropriately for debugging without exposing sensitive information
• Implement circuit breaker patterns for service resilience

Testing Considerations

• Test token attachment functionality with valid/invalid tokens
• Verify token refresh mechanisms work correctly
• Validate error response parsing across different error types
• Test API client behavior in both client and server contexts
• Verify proper cleanup and cancellation of requests
• Test concurrent request handling and token refresh coordination