Introduction
axios-retryer is a TypeScript-first retry manager for Axios that adds concurrency control, request prioritization, and an opt-in plugin layer for token refresh, response caching, circuit breaking, and more.
What problem does it solve?
Most Axios retry helpers stop at "try again after N milliseconds." Real production apps usually need more:
- Transient failures — 5xx spikes, timeouts, flaky networks, and 429 rate limits happen constantly.
- Authentication — Access tokens expire. Retrying correctly after a refresh, without firing multiple simultaneous refresh calls, is deceptively hard to get right.
- Concurrency — Browsers and Node workers can easily overwhelm an upstream if every request fires without any queue.
- Operational visibility — Once retries start happening, teams need metrics, events, and diagnostics to understand what the client is doing.
axios-retryer is built for that broader problem. You start with a small core and add only the plugins your app actually needs.
Design principles
- Small core, optional plugins — the root entry is focused on retry orchestration, queueing, and events. Everything else is an opt-in plugin with its own documented entry point.
- Tree-shakeable — each plugin ships as a separate entry point so unused code stays out of your bundle.
- TypeScript-first — all public API is typed, including plugin-specific events that widen the manager type through
use(). - Predictable behavior — strong defaults, named errors, and no hidden state.
Core vs plugin boundary
| What it does | Where it lives | Entry point |
|---|---|---|
| Retry orchestration, queue, concurrency | Core | axios-retryer |
| Request prioritization | Core | axios-retryer |
Lifecycle events (retryer.on) | Core | axios-retryer |
| Custom retry strategies | Core | axios-retryer |
| Named error classes | Core | axios-retryer |
| Priority-based queue blocking | Core | axios-retryer |
| Token refresh | Plugin | axios-retryer/plugins/TokenRefreshPlugin |
| Response caching | Plugin | axios-retryer/plugins/CachingPlugin |
| Circuit breaking | Plugin | axios-retryer/plugins/CircuitBreakerPlugin |
| Manual retry replay | Plugin | axios-retryer/plugins/ManualRetryPlugin |
| Debug log sanitization | Plugin | axios-retryer/plugins/DebugSanitizationPlugin |
| Metrics collection | Plugin | axios-retryer/plugins/MetricsPlugin |
Good fit for
- Frontend apps that need retries + token refresh + predictable concurrency
- Node.js services calling third-party APIs under rate limits
- TypeScript projects that want a typed retry manager instead of ad hoc interceptors
- Teams that want a single Axios integration point instead of scattered retry helpers
Probably not for
- Projects not using Axios
- Apps that only need "retry a GET a few times" and nothing more — a simpler helper is fine