Middleware System

The SDK’s middleware system provides automatic token management and request/response logging built on top of openapi-fetch. The middleware is internal to the SDK and handles authentication and debugging automatically.

Built-in Middleware

Authentication Middleware

Automatically handles token refresh and authentication for all requests when tokenStorage is provided:

import { StorefrontSDK, BrowserTokenStorage } from '@commercengine/storefront';

const client = createStorefront({
  storeId: 'your-store-id',
  apiKey: 'your-api-key',
  tokenStorage: new BrowserTokenStorage() // Enables auth middleware
});

// All requests automatically include valid tokens
const { data, error } = await client.catalog.listProducts();

if (data) {
  console.log(`Successfully fetched ${data.products.length} products.`);
} else if (error) {
  console.error("Failed to fetch products:", error.message);
}

Features:

Automatic token refresh before expiry
Anonymous token handling with API key
Token storage synchronization
Seamless authentication state transitions

Debug Middleware

Request/response logging for development when debug mode is enabled:

const client = createStorefront({
  storeId: 'your-store-id',
  apiKey: 'your-api-key',
  debug: true, // Enable debug middleware
  logger: (level, message, data) => {
    console.log(`[${level}] ${message}`, data);
  }
});

Logged Information:

Request URLs, headers, body
Response status, headers, body
Token refresh events
Error details
Network timing

Timeout Middleware

Request timeout handling when configured:

const client = createStorefront({
  storeId: 'your-store-id',
  apiKey: 'your-api-key',
  timeout: 30000 // 30 second timeout
});

Token Storage Integration

The SDK’s automatic token management requires a token storage implementation. For detailed information about all available token storage options, configuration, and best practices, see our comprehensive Token Management Guide.

Quick Setup

import { BrowserTokenStorage } from '@commercengine/storefront';

const client = createStorefront({
  storeId: 'your-store-id',
  apiKey: 'your-api-key',
  tokenStorage: new BrowserTokenStorage('my_app_')
});

The token storage you choose affects how the middleware handles authentication. See Token Management for complete storage options including BrowserTokenStorage, CookieTokenStorage, MemoryTokenStorage, and custom implementations.

Authentication Flow

The authentication middleware handles token management automatically:

Request Initiated

Client makes API request

Token Check

Middleware checks if access token exists and is valid

Token Refresh

If token is expired, automatically refreshes using refresh token

Storage Update

Updates token storage with new tokens

Request Completion

Original request proceeds with valid token

Manual Token Management

Without tokenStorage, tokens must be managed manually:

const client = createStorefront({
  storeId: 'your-store-id',
  apiKey: 'your-api-key',
  accessToken: 'your-access-token' // Manual token
});

// Update tokens manually
await client.setTokens('new-access-token', 'new-refresh-token');

// Clear tokens manually  
await client.clearTokens();

Framework-Specific Storage

For framework-specific token storage implementations and patterns:

Next.js Integration

Universal token storage for SSR/SSG applications

React Integration

Browser-based storage with React context patterns

Token Callbacks

React to token changes with callback functions:

const client = createStorefront({
  storeId: 'your-store-id',
  tokenStorage: new BrowserTokenStorage(),
  onTokensUpdated: (accessToken, refreshToken) => {
    console.log('Tokens updated:', { accessToken, refreshToken });
    // Update app state, analytics, etc.
  },
  onTokensCleared: () => {
    console.log('User logged out');
    // Redirect to login, clear app state, etc.
  }
});

Cross-References

Token Management: Token Management Guide for complete token handling documentation
Authentication API: Authentication Reference for endpoint details
Storefront Auth Guide: Authentication Best Practices for business logic

The middleware system is internal to the SDK and automatically configured based on your options. You cannot add custom middleware - the SDK handles authentication, debugging, and timeout management internally.

Getting Started

Core Features

Framework Integration

Advanced Usage

Built-in Middleware

Authentication Middleware

Debug Middleware

Timeout Middleware

Token Storage Integration

Quick Setup

Authentication Flow

Manual Token Management

Framework-Specific Storage

Next.js Integration

React Integration

Token Callbacks

Cross-References

​Built-in Middleware

​Authentication Middleware

​Debug Middleware

​Timeout Middleware

​Token Storage Integration

​Quick Setup

​Authentication Flow

​Manual Token Management

​Framework-Specific Storage

Next.js Integration

React Integration

​Token Callbacks

​Cross-References

Built-in Middleware

Authentication Middleware

Debug Middleware

Timeout Middleware

Token Storage Integration

Quick Setup

Authentication Flow

Manual Token Management

Framework-Specific Storage

Token Callbacks

Cross-References