DEV Community: Serhii Zhabskyi

I had four AI coding assistants and the same config in five places. Here's what I built.

Serhii Zhabskyi — Tue, 28 Apr 2026 08:31:01 +0000

A while back my repo looked like this:

CLAUDE.md                                        # rules for Claude Code
.claude/agents/code-reviewer.md                  # agent definitions
.claude/skills/refactor/SKILL.md                 # skill packs
.claude/commands/deploy.md                       # slash commands
.claude.json                                     # MCP servers
.cursor/rules/typescript.mdc                     # rules for Cursor
.cursor/mcp.json                                 # MCP servers (different schema)
.github/copilot-instructions.md                  # rules for Copilot
.github/agents/code-reviewer.md                  # agents (different format)
.continue/rules/typescript.md                    # rules for Continue
.continue/mcpServers/                            # MCP servers (yet another schema)

Same rule - "no any, prefer unknown with narrowing" - in four places. Same MCP server configured three times in three JSON schemas. Same code-reviewer agent described twice with different frontmatter. Same deployment command in two directories.

Then someone updated unknown to never for a specific case in CLAUDE.md only. Cursor still suggested unknown. Copilot agreed with neither. We spent a standup figuring out which AI was "right."

The problem wasn't rules alone. It was the entire config surface: rules, agents, skills, commands, MCP servers, hooks, permissions, and ignore files - all duplicated per tool, all drifting independently.

What I tried first

I looked for existing tools that solve this. The most popular one in this space has the right model: one canonical source, generate per-tool configs. I used it for a few months.

But I kept hitting gaps. Cross-references between files didn't get rewritten on generate, so an agent linking to a skill produced broken paths in every target. Activation semantics got inverted across tool dialects - a manual-only rule became always-on after translation. Hook configs got generated but the scripts they referenced didn't follow. Permissions weren't modeled as a feature at all. And every new AI coding tool that shipped needed a PR to the maintainer's repo — some requests sat open for over a year.

These aren't bugs. They're architectural limits that compound once you grow past flat rule syncing into the full config surface: agents, skills with supporting files, hooks with scripts, permissions, MCP servers with tool-specific schemas.

The pattern

You already use this pattern elsewhere:

package.json → package-lock.json
Dockerfile → image
*.proto → client SDKs

Apply it to AI configs:

One canonical directory describes rules, commands, agents, skills, MCP, hooks, ignore, and permissions in a tool-agnostic way.
A generator projects them into each tool's native format.
An importer does the reverse, so you can adopt without rewriting existing configs.
A lock file detects drift in CI.

The interesting work is in the link rewriting, the round-trip story, and getting the full feature surface (not just rules) to project correctly across 12 tools.

What I built

agentsmesh implements this pattern. Here's the canonical directory and what it generates:

.agentsmesh/                           Generated output (Claude Code):
├── rules/                             ├── CLAUDE.md
│   ├── _root.md                       ├── .claude/
│   └── typescript.md                  │   ├── rules/typescript.md
├── agents/                            │   ├── agents/code-reviewer.md
│   └── code-reviewer.md              │   ├── skills/refactor/
├── skills/                            │   │   ├── SKILL.md
│   └── refactor/                      │   │   └── references/patterns.md
│       ├── SKILL.md                   │   ├── commands/deploy.md
│       └── references/                │   └── settings.json  (hooks, perms)
│           └── patterns.md            ├── .claude.json        (MCP)
├── commands/                          
│   └── deploy.md                      Generated output (Cursor):
├── mcp.json                           ├── .cursor/
├── hooks.yaml                         │   ├── rules/
├── permissions.yaml                   │   │   ├── _root.mdc
└── ignore                             │   │   └── typescript.mdc
                                       │   ├── skills/refactor/
                                       │   │   ├── SKILL.md
                                       │   │   └── references/patterns.md
                                       │   └── mcp.json
                                       ├── AGENTS.md (agents + commands embedded)
                                       └── .cursorignore

One canonical source. Two different generated trees with different directory layouts, different file formats, different frontmatter conventions — all from the same .agentsmesh/ input.

Adopt in an existing project:

npx agentsmesh import --from cursor   # or claude-code, copilot, codex-cli, ...
npx agentsmesh generate

import walks your existing tool config, normalizes it into the canonical shape. generate projects it back out to every enabled tool.

Cross-references get rewritten per-target

This is the part I underestimated.

When the code-reviewer agent file says "see the refactor skill for the full playbook", that link has to resolve differently in every generated output:

Target	The agent's skill link resolves to
Claude Code	`.claude/skills/refactor/SKILL.md`
Cursor	`.cursor/skills/refactor/SKILL.md`
Codex CLI	`.codex/skills/refactor/SKILL.md`
Claude Code (global)	`~/.claude/skills/refactor/SKILL.md`

The rebaser at src/core/reference/link-rebaser.ts rewrites every link per target. The rules are explicit:

Inside .agentsmesh/ → relative paths.
Outside .agentsmesh/ in project mode → repo-root absolute paths.
Outside .agentsmesh/ in global mode → no rewrite. Your home directory isn't mine to touch.
Markdown link URLs stay relative for portability.

Without this you can't have agents referencing skills, skills referencing other skills, rules pointing at commands. You're forced to keep everything in one flat file with no cross-references.

Lossless round-trip across the full feature surface

When a target doesn't natively support a feature (Cursor has no native skills directory, Copilot has no native hooks), the generator embeds them with metadata so re-importing reconstructs the original shape.

This matters for more than just rules:

Skills with supporting files (references, templates, scripts) survive projection to tools that don't have a skills directory — they get embedded in the root instructions with metadata markers.
Agents defined in .agentsmesh/agents/code-reviewer.md become .claude/agents/code-reviewer.md for Claude (native), or get embedded in AGENTS.md for Cursor and Codex (which read that file).
Commands become .claude/commands/deploy.md for Claude, .gemini/commands/deploy.toml for Gemini (different format entirely), or get embedded in the root instructions for tools that don't have a commands directory.
Activation semantics survive too — Cursor's alwaysApply: false round-trips through Claude generation and back into canonical form without getting inverted.

Hooks and permissions are first-class

hooks.yaml and permissions.yaml are canonical types alongside rules and skills. Hooks generate in each target's native format — JSON config in settings for Claude, wrapper scripts for Copilot, per-file .kiro.hook for Kiro. Permissions project to native settings where the target supports it (currently Claude Code has full native support; others embed or partially support).

Targets are data, not classes

A target is a TargetDescriptor value declared in src/targets/<id>/index.ts. The engine reads the descriptor and dispatches generically — it never branches on target name. Capability levels (native | embedded | partial | none) are declared per feature in the descriptor:

capabilities: {
  rules: 'native',
  commands: 'native',
  agents: 'embedded',    // no native agent dir → embed in root instructions
  skills: 'native',
  mcp: 'native',
  hooks: 'partial',      // limited event support
  permissions: 'none',
  ignore: 'native',
}

The builtin catalog is auto-discovered at build time by scanning src/targets/*/index.ts. agentsmesh target scaffold foo-ide generates the full structure — descriptor, generators, importer, linter, constants, tests — so you start from a working base. No enum to update, no shared code to edit.

Plugins ship as standalone npm packages

npx agentsmesh plugin add agentsmesh-target-foo-ide
npx agentsmesh generate

Plugins get full built-in parity — same descriptor schema, same capability levels, same lint hooks and global-mode support as built-ins. New tool support doesn't wait for me.

CI/dev workflow

- run: npx agentsmesh check    # exits 1 on drift

The rest of the surface:

agentsmesh diff — preview what generate would change, without writing.
agentsmesh lint — validate canonical config against per-target constraints.
agentsmesh watch — regenerate target files on save during local editing.
agentsmesh merge — resolve three-way .lock conflicts after git merge.
agentsmesh matrix — print the full support matrix for all targets and features.

Global mode for personal config

npx agentsmesh init --global
npx agentsmesh import --global --from claude-code
npx agentsmesh generate --global   # writes ~/.claude/, ~/.cursor/, ~/.codex/, ...

~/.agentsmesh/ is for personal setup across every repo you touch. Every CLI command accepts --global.

Native Windows

Path-format detection (/proj vs C:\proj) decoupled from host platform. chokidar polling on Windows for ReadDirectoryChangesW edge cases. basename() everywhere instead of split('/'). CI matrix runs Linux + macOS + Windows.

Typed programmatic API

Same surface as the CLI, exported with full .d.ts under strict TS:

import { loadProjectContext, generate, lint, diff, check } from 'agentsmesh';

const project = await loadProjectContext(process.cwd());
await generate(project);
const drift = await check(project);

Subpath imports for narrower bundles: agentsmesh/engine, agentsmesh/canonical, agentsmesh/targets.

JSON Schema for every config

agentsmesh.yaml, hooks.yaml, permissions.yaml, mcp.json, pack.json — all ship with generated $schema references. VS Code and JetBrains autocomplete + validation work out of the box.

Community packs

npx agentsmesh install github:org/shared-config@v1.0.0
npx agentsmesh install --sync    # restore all packs after clone

Packs live in .agentsmesh/packs/, track in installs.yaml, and merge into canonical config on every generate.

What it doesn't do

No GUI. It's a CLI and a library.
Doesn't manage secrets. MCP server tokens stay in your existing secret store.
Won't help if you only use one tool. The canonical layer is overhead.
Smaller ecosystem. Fewer community packs and fewer eyes on it.

Try it

npm install -D agentsmesh
npx agentsmesh init
# or, in an existing project:
npx agentsmesh import --from cursor
npx agentsmesh generate

Linux, macOS, Windows (native, not WSL). MIT. Node 20+. ESM-only. Strict TypeScript.

Source: github.com/sampleXbro/agentsmesh · Docs: samplexbro.github.io/agentsmesh

Supercharge Your Axios Requests: axios-retryer for Robust API Communication

Serhii Zhabskyi — Sat, 24 May 2025 15:52:24 +0000

I’ve been working on a React application that needed a robust solution for handling concurrent requests, custom retry logic, and token refresh—without shuffling together multiple scattered packages. I couldn’t find an all-in-one library that combined concurrency management, priorities, token refresh, caching, and circuit breaking in a straightforward API, so I built axios-retryer.

📝 Why I Wrote It

In this TV-based frontend project some data requests were absolutely critical (e.g., user authentication or top-level layout info) and needed to complete before all the nice-to-have background calls. Sure, I could let Axios blasts run wild, but that risked important calls getting stuck behind less urgent tasks. I also hated duplicating retry logic across different request modules. So, I decided to create a single “retryer” layer for concurrency, priority handling, advanced retry strategies, token refreshing, circuit-breaking, caching, and analytics events. Doing so helped me replace multiple incomplete solutions with a single, consistent approach.

🚀 Key Features at a Glance

Priority & Concurrency: Queue requests so critical calls finish before everything else, with fine-grained control over simultaneous requests.
Customizable Retry Strategies: Built-in linear, exponential backoff, static, or provide your own custom retry logic function.
TokenRefreshPlugin: Automatically refresh access tokens upon expiry and seamlessly replay pending requests.
CircuitBreakerPlugin: Intelligently detect repeated errors from an endpoint and temporarily halt requests to avoid further failures, then gracefully recover.
CachingPlugin: Cache responses for common requests to reduce load times and bandwidth usage.
Metrics & Events: Observe request outcomes, success/failure rates, circuit states, and other vital statistics through a rich event system.
Minimal Overhead: Approximately 6.4 kB minified + gzipped (core library with all plugins) means it won’t bloat your bundle.

⚙️ Quick Install & Hello World

Installation is straightforward using npm, yarn, or pnpm. Here’s the minimal setup to get you started:

# Using npm
npm install axios-retryer

# Using yarn
yarn add axios-retryer

// Import the library
import { createRetryer } from 'axios-retryer';

async function main() {
  // Create a retryer instance with sensible defaults
  const retryer = createRetryer({
    retries: 3, // Attempt requests up to 3 times on failure
    debug: false // Set to true for development logging
  });

  // Use the axiosInstance provided by the retryer
  try {
    const response = await retryer.axiosInstance.get('https://api.example.com/data');
    console.log('Data:', response.data);
  } catch (error) {
    console.error('All retries failed:', error);
  }
}

main();

That’s the essence: createRetryer() returns a manager object, and you use its axiosInstance property, which is a specially configured Axios instance with concurrency, retry logic, and plugin support baked in.

Priority & Concurrency

Priority and concurrency control were the main motivators for this library. In many applications, you can’t just fire off 20 requests simultaneously and hope they resolve in the right order. Instead, you often need to limit how many calls happen at once (maxConcurrentRequests), while also ensuring critical requests jump the queue (__priority).

Concurrency: If you set maxConcurrentRequests to, say, 2, axios-retryer will ensure that no more than two requests are in-flight at any given time. This can mitigate server load and prevent the UI from becoming unresponsive under heavy network traffic.
Priority: By passing a __priority option (numeric, typically using predefined constants) in your request config, you can dictate which requests get processed first from the queue. Lower numeric priority values in the constants (e.g., CRITICAL) mean higher actual priority.

Here’s a TypeScript snippet demonstrating this:

import { createRetryer, AXIOS_RETRYER_REQUEST_PRIORITIES } from 'axios-retryer';

const retryer = createRetryer({
  maxConcurrentRequests: 2, // Max two concurrent requests
  // Requests with priority >= HIGH will block lower priority ones
  blockingQueueThreshold: AXIOS_RETRYER_REQUEST_PRIORITIES.HIGH
});

async function exampleRequests() {
  // Critical request - gets processed sooner, potentially blocking others
  retryer.axiosInstance.get('/critical-endpoint', {
    __priority: AXIOS_RETRYER_REQUEST_PRIORITIES.CRITICAL
  }).then(response => console.log('Critical data received:', response.data));

  // Standard important request
  retryer.axiosInstance.get('/user-profile', {
    __priority: AXIOS_RETRYER_REQUEST_PRIORITIES.HIGH
  }).then(response => console.log('User profile received:', response.data));

  // Lower priority request - waits if concurrency is at capacity or blocked
  retryer.axiosInstance.get('/background-sync', {
    __priority: AXIOS_RETRYER_REQUEST_PRIORITIES.LOW
  }).then(response => console.log('Background sync complete:', response.data));
}

exampleRequests();

Behind the scenes, axios-retryer manages an internal priority queue. When maxConcurrentRequests is reached, new requests are enqueued. Within that queue, items are sorted by their __priority. The blockingQueueThreshold adds another layer, ensuring that no requests with a priority lower than the threshold are processed if higher-priority requests are pending.

Retry Strategies (Linear, Exponential, Static, Custom)

We’ve all implemented the typical "retry a request 3 times if it fails," but sometimes a more sophisticated approach is needed. axios-retryer supports various backoff strategies:

Linear: Increments wait times consistently (e.g., 1s, 2s, 3s).
Exponential: Doubles the backoff period with each attempt (e.g., 1s, 2s, 4s, 8s). This is the default.
Static: Static backoff period (e.g. 2s, 2s, 2s, 2s).
Custom: Pass your own function to calculate delays.

You configure the retry behavior within the createRetryer options:

import { createRetryer, AXIOS_RETRYER_BACKOFF_TYPES } from 'axios-retryer';

const retryer = createRetryer({
  retries: 3, // Total retry attempts
  backoffType: AXIOS_RETRYER_BACKOFF_TYPES.EXPONENTIAL, // 'linear', 'exponential', 'static'
  // You can also specify retryable HTTP methods and status codes
  retryableMethods: ['get', 'head', 'options', 'put'],
  retryableStatuses: [408, 429, [500, 599]] // Retries on 408, 429, or 5xx
});

// This request will use the exponential backoff strategy defined above
retryer.axiosInstance.get('/some-flaky-endpoint')
  .catch(err => console.error('Failed after exponential backoff retries:', err));

For a completely custom strategy, you can provide a retryStrategy object with isRetryable, shouldRetry, and getDelay functions:

import { createRetryer, createRetryStrategy } from 'axios-retryer';

const customStrategy = createRetryStrategy({
  isRetryable: (error) => !error.response || (error.response.status >= 500 && error.response.status < 600),
  shouldRetry: (error, attempt, maxRetries) => {
    if (error.config?.method?.toLowerCase() === 'post' && attempt >= 1) {
      return false; // Don't retry POST requests more than once
    }
    return attempt < maxRetries; // Note: attempt is 0-indexed for calculation
  },
  getDelay: (attempt) => (attempt + 1) * 1000 + (Math.random() * 500) // Linear backoff with jitter
});

const customRetryer = createRetryer({
  retries: 4,
  retryStrategy: customStrategy
});

customRetryer.axiosInstance.post('/another-endpoint', { data: 'payload' })
  .catch(err => console.error('Failed with custom strategy:', err));

The library automatically handles the asynchronous timeouts for you.

TokenRefreshPlugin (Single Refresh + Replay)

Dealing with expired authentication tokens is a common pain point, especially if multiple requests are made around the token's expiration time. The TokenRefreshPlugin simplifies this by detecting token-related errors (typically 401 Unauthorized), automatically fetching a new token (once per expiration cycle), and then replaying the requests that failed due to the expired token.

Here’s how you set it up:

import { createRetryer } from 'axios-retryer';
import { createTokenRefreshPlugin } from 'axios-retryer/plugins/TokenRefreshPlugin';
import axios from 'axios'; // Import base axios for the refresh function if needed

const retryer = createRetryer({
  maxConcurrentRequests: 3
  // other configurations...
});

const tokenRefreshPlugin = createTokenRefreshPlugin(
  async (axiosInstanceForRefresh) => {
    // This function is called to get a new token
    // It receives an Axios instance specifically for the refresh call
    // to avoid circular dependencies with the retryer's interceptors.
    console.log('Attempting to refresh token...');
    const refreshToken = localStorage.getItem('refreshToken');
    // Use a clean axios instance for the refresh call
    const { data } = await axios.post('/auth/refresh', { refreshToken });
    localStorage.setItem('accessToken', data.accessToken);
    console.log('Token refreshed successfully.');
    return { token: data.accessToken }; // Must return the new token
  },
  {
    // Optional configuration for the plugin
    authHeaderName: 'Authorization',    // Default: 'Authorization'
    tokenPrefix: 'Bearer ',             // Default: 'Bearer '
    refreshStatusCodes: [401],          // Default: [401]
    maxRefreshAttempts: 2,              // Default: 3
    // Custom detector for APIs that don't use 401 (e.g., GraphQL)
    customErrorDetector: (response) => {
      return response?.data?.errors?.some(
        (err: any) => err.extensions?.code === 'UNAUTHENTICATED' || err.message?.includes('token expired')
      );
    }
  }
);

// Add the plugin to the retryer instance
retryer.use(tokenRefreshPlugin);

// Now, requests made with retryer.axiosInstance will benefit from auto token refresh
retryer.axiosInstance.get('/secure-data')
  .then(response => console.log('Secure data:', response.data))
  .catch(error => console.error('Failed to get secure data:', error));

When a request returns a status code matching refreshStatusCodes (or if customErrorDetector returns true), the plugin pauses outgoing requests, executes your fetchNewToken function, updates the default headers of the retryer.axiosInstance with the new token, and then replays the original failed request and any other requests that were queued while the token was being refreshed.

CircuitBreakerPlugin

To prevent an application from repeatedly trying to connect to a service that is known to be failing, you can use the CircuitBreakerPlugin. Once a configured error threshold is met (e.g., 5 failed requests in a row), the circuit "opens," and subsequent requests to that service fail immediately (short-circuit) without hitting the network. After a cooldown period, the circuit transitions to a "half-open" state, allowing a limited number of test requests. If these succeed, the circuit "closes" and normal operation resumes. If they fail, it re-opens.

import { createRetryer } from 'axios-retryer';
import { createCircuitBreaker } from 'axios-retryer/plugins/CircuitBreakerPlugin'; // Corrected import name

const retryer = createRetryer({
  // other configurations...
});

const circuitBreakerPlugin = createCircuitBreaker({
  failureThreshold: 5,     // Trip after 5 consecutive failures
  openTimeout: 30000,      // Stay open for 30 seconds
  halfOpenMax: 2,          // Allow 2 test requests in half-open state
  successThreshold: 2,     // Need 2 successes in half-open to close
  useSlidingWindow: false  // Set to true for time-based failure counting
});

retryer.use(circuitBreakerPlugin);

// Requests to a consistently failing service will eventually be short-circuited
function fetchDataRepeatedly() {
  retryer.axiosInstance.get('/unreliable-service')
    .then(response => console.log('Service responded:', response.data))
    .catch(error => {
      console.error('Service call failed:', error.message);
      if (error.isAxiosError && error.message.includes('Circuit is open')) {
        console.log('Circuit breaker is open, not attempting network request.');
      }
    });
}

// Simulate multiple calls
// setInterval(fetchDataRepeatedly, 2000);

This pattern is crucial for building resilient applications that can gracefully handle temporary outages of downstream services.

CachingPlugin

The CachingPlugin (using createCachePlugin) helps you cache responses from specific endpoints, reducing unnecessary network calls and improving perceived performance. You can configure cache lifetime, which HTTP methods to cache, and more.

import { createRetryer } from 'axios-retryer';
import { createCachePlugin } from 'axios-retryer/plugins/CachingPlugin'; // Corrected import name

const retryer = createRetryer({
  // other configurations...
});

const cachePlugin = createCachePlugin({
  timeToRevalidate: 60 * 1000, // Cache entries for 1 minute (in ms)
  cacheMethods: ['GET'],       // Only cache GET requests (default)
  cleanupInterval: 5 * 60 * 1000, // Check for stale entries every 5 minutes
  maxItems: 100,               // Store up to 100 cached items
  compareHeaders: false,       // Set to true to include headers in cache key
  cacheOnlyRetriedRequests: false // Set to true to only cache successful retried requests
});

retryer.use(cachePlugin);

async function fetchCachedData() {
  console.log('Fetching /static-data...');
  const response1 = await retryer.axiosInstance.get('/static-data');
  console.log('Data 1:', response1.data, '(from network or cache)');

  console.log('Fetching /static-data again...');
  const response2 = await retryer.axiosInstance.get('/static-data');
  console.log('Data 2:', response2.data, '(likely from cache if within TTR)');
}

fetchCachedData();

// You can also control caching on a per-request basis
retryer.axiosInstance.get('/api/realtime-updates', {
  __cachingOptions: {
    cache: false // Disable caching for this specific request
  }
});

retryer.axiosInstance.post('/api/submit-form', { data: 'content' }, {
  __cachingOptions: {
    cache: true, // Force caching for this POST request (if method allowed globally)
    ttr: 30000   // Custom Time To Revalidate: 30 seconds
  }
});

The plugin automatically generates cache keys based on the request URL, method, and optionally headers. It provides methods to invalidate or clear the cache programmatically.

Metrics/Events

Monitoring real-time performance and understanding request behavior can help you catch bottlenecks or diagnose issues. axios-retryer emits a variety of events throughout the request lifecycle, allowing you to wire up custom analytics or logging.

You subscribe to these events using the on method of the retryer instance:

import { createRetryer } from 'axios-retryer';

const retryer = createRetryer({ debug: true }); // Enable debug for more event logs

retryer
  .on('onRetryProcessStarted', (requestConfig) => {
    console.log(`[Event] Retry process started for: ${requestConfig.url}`);
  })
  .on('beforeRetry', (requestConfig, attemptInfo) => {
    console.log(`[Event] Before retry attempt ${attemptInfo.attemptNumber} for: ${requestConfig.url}`);
  })
  .on('afterRetry', (requestConfig, attemptInfo, wasSuccessful) => {
    console.log(`[Event] After retry attempt ${attemptInfo.attemptNumber} for: ${requestConfig.url}. Success: ${wasSuccessful}`);
  })
  .on('onRetryProcessFinished', (requestConfig, metrics) => {
    console.log(`[Event] Retry process finished for: ${requestConfig.url}. Metrics:`, metrics);
    // metrics include totalAttempts, wasSuccessful, etc.
  })
  .on('onMetricsUpdated', (globalMetrics) => {
    // These are overall metrics for the retryer instance
    // console.log('[Event] Global metrics updated:', globalMetrics);
    // updateDashboard(globalMetrics);
  })
  .on('onTokenRefreshed', (newToken) => {
    console.log('[Event] Token was successfully refreshed.');
  });

// Example request to trigger events
retryer.axiosInstance.get('https://api.example.com/flaky')
  .catch(() => console.log('Request to flaky endpoint eventually failed or succeeded.'));

The globalMetrics object provided by onMetricsUpdated includes counts for total requests, successful retries, failed retries, and new timer health statistics to help monitor event loop congestion.

💡 Less-Obvious Use Cases

Beyond the standard retry or concurrency scenarios, here are some other ways axios-retryer can be beneficial:

Offline-First PWAs: In Progressive Web Apps, use mode: 'manual' to store failed requests when offline. When the connection is re-established, call retryer.retryFailedRequests() to sync critical data, respecting priorities.
Serverless Edge Functions: When calling external APIs from environments with strict concurrency limits (like some edge function providers), maxConcurrentRequests helps stay within quotas.
React Query/SWR Adapter: While libraries like React Query or SWR handle their own caching and some retries, axios-retryer can manage the underlying Axios instance to provide global concurrency limits, priority queuing, and standardized token refresh logic for all data fetches.
Robust Microservice Communication (Node.js): If your Node.js backend acts as an API gateway or communicates with multiple microservices, axios-retryer (with plugins like Circuit Breaker) can make these interactions more resilient.
Batch Data Uploads/Processing: For scenarios where you need to upload many items or process a batch of API calls, concurrency control ensures you don't overwhelm the server, and retries handle intermittent failures gracefully.
Web Scraping Responsibly: When scraping data, use maxConcurrentRequests and appropriate backoff strategies with queueDelay to avoid overwhelming the target server and to respect its rate limits.

📈 Performance & Bundle Size

axios-retryer is designed to be efficient. The core library, including all plugins, comes in at approximately 6.4 kB minified and gzipped. The plugin system is modular, so if you don't use a plugin, its code won't be included in your bundle when using tree-shaking.

Performance considerations:

The priority queue uses efficient data structures (like a binary heap) for O(log n) operations.
Retry strategies add minimal overhead, primarily driven by JavaScript timers.
The new timer management system actively monitors and helps prevent event loop congestion from excessive timers.

It should integrate smoothly into typical front-end or Node.js projects without significantly impacting bundle size or runtime performance.

🛣️ Roadmap & Contribution Call

I have several features and improvements planned for future releases:

WebSocket Reconnection Plugin: A dedicated plugin to manage robust WebSocket connections, including automatic reconnection with backoff strategies.
DevTools Panel: A browser extension (e.g., for Chrome/Firefox DevTools) to visualize the request queue, circuit breaker states, cache contents, and active timers.
More Granular Cache Control: Advanced cache invalidation strategies and tagging.

Contributions are highly welcome! Whether it's tackling one of these features, suggesting new ones, improving documentation, or reporting bugs, your input is valuable. Please check out the CONTRIBUTING.md file on GitHub, open an issue to discuss your ideas, or submit a pull request.

🏁 Conclusion / CTA

If you're tired of cobbling together solutions for API request concurrency, complex retries, token refreshing, circuit breaking, and caching, axios-retryer offers a unified and powerful approach.

Install: npm install axios-retryer

Explore the documentation, examples, and source code on GitHub. If you find it useful, please consider giving it a star! I’d love to hear your feedback, learn about your use cases, and see how axios-retryer can be improved to better serve the developer community.