Plugins

The core stays lean. Plugins are independent, tree-shakeable entry points you add only when you need them. Each plugin has its own documented import path.

💡

Prefer subpath imports

Import from focused paths like axios-retryer/plugins/TokenRefreshPlugin so bundlers tree-shake unused plugins. The convenience barrel axios-retryer/plugins bundles everything unconditionally and will be removed in v3.

🧱

Building your own plugin?

Follow the single recommended repo pattern for plugin authoring: orchestrator class, focused folders, explicit events, and isolated state boundaries. See Creating Plugins.

Registering multiple plugins

use() returns the same manager instance and widens the TypeScript event map. Chain plugins on one expression (or reassign each use() result) so on() knows about every plugin’s events. See Events for the typing rules and an optional RetryManager<YourComposedEvents> pattern.

import { createRetryer } from 'axios-retryer';
import { createTokenRefreshPlugin } from 'axios-retryer/plugins/TokenRefreshPlugin';
import { createCircuitBreaker } from 'axios-retryer/plugins/CircuitBreakerPlugin';
import { createMetricsPlugin } from 'axios-retryer/plugins/MetricsPlugin';

export const api = createRetryer({ retries: 3 })
  .use(createTokenRefreshPlugin(async (axios) => {
    const { data } = await axios.post('/auth/refresh');
    return { token: data.accessToken };
  }))
  .use(createCircuitBreaker({ failureThreshold: 5, openTimeout: 30_000 }))
  .use(createMetricsPlugin());

api.on('onTokenRefreshed', (token) => console.log(token));
api.on('onMetricsUpdated', (m) => console.log(m.successfulRetries));

🔑 TokenRefreshPlugin

axios-retryer/plugins/TokenRefreshPlugin

Automatically refreshes JWT/OAuth tokens when requests return 401. Queues all concurrent requests during the refresh, then replays them with the new token. Supports customErrorDetector for GraphQL APIs that return errors in 200 bodies. You can resolve the refresh callback with no token to skip a cycle without failure events.

View docs →

Use when

Access tokens expire and protected routes need silent replay after refresh
Multiple concurrent requests can race on a 401
Auth errors appear in 200 response bodies (GraphQL)

🛡️ CircuitBreakerPlugin

axios-retryer/plugins/CircuitBreakerPlugin

Trips open after N failures, fast-fails all subsequent requests during the recovery window, then allows configurable half-open probes. Supports sliding window analysis and URL exclusion patterns.

View docs →

Use when

A failing upstream should stop receiving requests while recovering
You want to reduce latency during partial outages
Downstream rate limits need enforced back-off at the client

💾 CachingPlugin

axios-retryer/plugins/CachingPlugin

Caches responses in memory with configurable TTR, exact/prefix/regex invalidation, per-request overrides, and a pluggable storage adapter contract (e.g. Redis, Memcached).

View docs →

Use when

Repeated identical reads should be deduped or served from memory
You want to reduce server load for stable read data
Offline-first data should be available from a previous response

💾 ManualRetryPlugin

axios-retryer/plugins/ManualRetryPlugin

Stores terminal failures (in MANUAL mode) and lets you replay them on demand. Built-in idempotency safeguards, auth-request skipping, and age limits.

View docs →

Use when

Offline-first SPA needs to queue requests while disconnected
User should manually trigger retry after reviewing failures
Failed mutations must survive a page reload

📊 MetricsPlugin

axios-retryer/plugins/MetricsPlugin

Activates live retry counters, success rates, failure counts, and timer health reporting. Without this plugin getMetrics() returns a zeroed snapshot.

View docs →

Use when

You need real-time retry metrics for dashboards or alerting
onMetricsUpdated events are required in your monitoring pipeline

🔒 DebugSanitizationPlugin

axios-retryer/plugins/DebugSanitizationPlugin

Redacts sensitive headers, body fields, and URL params from plugin-managed debug logs. Safe debug: true in non-prod environments.

View docs →

Use when

Debug logs must not leak tokens, passwords, or PII
Verbose logging is needed in staging but logs are shipped externally