axios-retryer

library2.3.2jsnpmunverified

TypeScript-first Axios retry library (v2.3.2) with concurrency limits, priority queues, token refresh, response caching, and circuit breaker plugins. Active development, monthly releases. Key differentiators: tree-shakeable plugin architecture, ESM-only from v2, full type safety, binary-heap priority scheduling, and composable lifecycle hooks. Compared to axios-retry or retry-axios, it adds concurrency control and circuit breaking out of the box.

testing

npm install axios-retryer

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AXIOS-RETRYER

axios-retryer

testingjavascriptv2.3.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createRetryer

✓ import { createRetryer } from 'axios-retryer'

✗ const { createRetryer } = require('axios-retryer')

ESM-only since v2. CommonJS require() will fail. Use dynamic import() if needed.

createTokenRefreshPlugin

✓ import { createTokenRefreshPlugin } from 'axios-retryer/plugins/TokenRefreshPlugin'

✗ import { createTokenRefreshPlugin } from 'axios-retryer'

Each plugin is a separate entry point to enable tree-shaking. Importing from main index will get the default export, not the plugin.

createCircuitBreaker

✓ import { createCircuitBreaker } from 'axios-retryer/plugins/CircuitBreakerPlugin'

✗ import { createCircuitBreaker } from 'axios-retryer'

Same as token refresh: plugins are in separate paths to keep bundle small.

Creates an axios-retryer instance with token refresh and circuit breaker plugins, then uses it to execute a GET request with automatic retries and error handling.

import { createRetryer } from 'axios-retryer'; import { createTokenRefreshPlugin } from 'axios-retryer/plugins/TokenRefreshPlugin'; import { createCircuitBreaker } from 'axios-retryer/plugins/CircuitBreakerPlugin'; import axios from 'axios'; const retryer = createRetryer({ retries: 3, maxConcurrentRequests: 10, }) .use( createTokenRefreshPlugin(async (axiosInstance) => { const { data } = await axiosInstance.post('/auth/refresh'); return { token: data.accessToken }; }), ) .use(createCircuitBreaker({ failureThreshold: 5, openTimeoutMs: 30000 })); export async function fetchData(url: string) { const response = await retryer.execute(() => axios.get(url)); // Response is already unwrapped (AxiosResponse) return response.data; }

Debug

Known issues

breakingESM-only since v2 — CommonJS require() imports will fail.

fix

Use import syntax or dynamic import(). If package.json type: module is not possible, use a bundler that can handle ESM.

affects: >=2.0.0

breakingPlugin imports changed in v2 — previously imported from 'axios-retryer/lib/plugins', now from 'axios-retryer/plugins/PluginName'.

fix

Update import paths: for example, import { createCircuitBreaker } from 'axios-retryer/plugins/CircuitBreakerPlugin'.

affects: >=2.0.0

breakingcreateRetryer() now returns a builder object, not the retryer instance directly. Must call .use() and then .build() or invoke .execute() which implicitly builds.

fix

Chain .use() calls and then call .execute() or .build(). See quick start example.

affects: >=2.0.0

deprecatedThe 'cache' option in createRetryer() options is deprecated; use createCachePlugin() instead.

fix

Replace 'cache' config with import { createCachePlugin } from 'axios-retryer/plugins/CachePlugin' and add it via .use().

affects: >=2.0.0

gotchaToken refresh plugin's refresh function receives the axios instance, not the retryer. Using an external axios instance may cause infinite loops if that instance also retries.

fix

Always use the axios instance passed to the refresh function — it's the same instance used for the original request.

affects: >=1.0.0

gotchamaxConcurrentRequests defaults to 1, not unlimited. Many users expect parallel execution out of the box.

fix

Set maxConcurrentRequests to a higher number (e.g., 10) in createRetryer() options.

affects: >=1.0.0

gotchaCircuit Breaker open state: after openTimeoutMs, it transitions to half-open and allows one trial request. If that request fails, it goes back to open; if it succeeds, it closes. This is default behavior and may not suit all use cases.

fix

Adjust failureThreshold and openTimeoutMs to match your application's tolerance.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: createRetryer is not a function

Using CommonJS require() instead of ESM import.

fix

Switch to import { createRetryer } from 'axios-retryer' or use dynamic import().

Cannot find module 'axios-retryer/plugins/CircuitBreakerPlugin'

Plugin path is incorrect or the package version is outdated (before v2).

fix

Update to axios-retryer@2.x and use import { createCircuitBreaker } from 'axios-retryer/plugins/CircuitBreakerPlugin'.

Error: No axios instance provided or configured

createRetryer() was called without an axios instance, or the instance was not passed to execute() and none was configured globally.

fix

Pass an axios instance to createRetryer({ axios: axiosInstance }) or provide one to retryer.execute(() => axios.get(...)).

UnhandledPromiseRejectionWarning: TypeError: Failed to fetch (or similar network error)

All retries exhausted or circuit breaker is open.

fix

Check if the upstream is reachable, increase retries, adjust backoff strategy, or inspect circuit breaker state logs.

Upgrade

Version history

2.3.2latest on npm

Audit

Dependencies

axiosoptionalPeer dependency: axios >= 1.7.4 is required for all retry and plugin functionality.

Agent activity

16 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/sampleXbro/axios-retryer ↗

packageaxios-retryer ↗

homepagehttps://github.com/sampleXbro/axios-retryer#readme ↗