Axios: A Promise-Based HTTP Client for Browser and Node.js

What Axios Does and Why It Persists in Modern Stacks

Axios solves two problems that appeared frequently when JavaScript ran in both browsers and server-side environments: the browser and Node.js used entirely different APIs for HTTP, and neither offered built-in request or response interceptors. Axios wraps the browser's XMLHttpRequest and Node.js's http module behind one consistent interface, returning promises. It handles JSON serialization and deserialization automatically, converts HTTP error status codes into rejected promises, and provides a composable interceptor chain for authentication headers, logging, and retry logic. The library predates the native fetch API becoming widely available and has accumulated a large installed base. Teams that adopted it before fetch was stable often keep it to avoid rewriting interceptor logic.

How Axios Routes Requests Between XHR and Node.js's http

Axios uses an adapter pattern to select the underlying transport at runtime. In a browser environment it uses the XMLHttpRequest adapter; in Node.js it uses the Node.js http and https modules. The package.json exports field defines separate entry points: browser environments resolve to dist/browser/axios.cjs, Node.js to dist/node/axios.cjs, and Bun to dist/node/axios.cjs. React Native resolves to dist/browser/axios.cjs. This adapter selection is automatic; no configuration is required in typical use. The exports field also exposes internal modules under unsafe/ paths for advanced consumers who need to import core utilities such as settle, buildURL, or combineURLs directly, though these paths carry no stability guarantee based on the naming convention in the exports map.

Installing Axios and Making a First Request

Install axios from npm using the package name declared in package.json:

npm install axios

The package ships TypeScript declarations in index.d.ts (ES module consumers) and index.d.cts (CommonJS consumers), so no separate types package is needed. Version 1.20.0 is the current stable release. The library is also available directly from a CDN using the jsdelivr or unpkg paths defined in package.json, which point to dist/axios.min.js. The examples directory in the repository contains subdirectories for common use cases including abort-controller, get, post, and postMultipartFormData, giving concrete starting points for each operation type.

TypeScript Support and Module Format Details

Axios ships two declaration files. index.d.ts serves ES module consumers and index.d.cts serves CommonJS consumers. This split matters because TypeScript resolves types differently depending on the moduleResolution setting. The tsconfig.json in the repository uses standard TypeScript configuration, and the exports field in package.json includes a types subfield that points to both .cts and .ts declarations depending on the require or default condition. The package distributes an ESM entry via index.js at the root and CJS bundles in dist/. The rollup.config.js in the repository drives the build, producing the browser CJS bundle, the Node.js CJS bundle, and the UMD build in dist/. Consumers using bundlers that honor the exports field get the correct adapter automatically.

Known Limitations and Cases Where Axios Is a Poor Fit

Axios does not support HTTP/2 natively; the Node.js adapter uses the http module, which is HTTP/1.1 by default. Response streaming works differently than in the fetch API: axios buffers the full response body unless specific stream handling is configured, which can be a concern for large downloads. The library's interceptor API is powerful but can make debugging harder when multiple interceptors are chained, since errors may originate anywhere in the chain. Axios also adds a non-trivial bundle size to browser applications. Projects targeting only modern browsers where the native fetch API is available, and where interceptors are not needed, may not benefit from the dependency. The v0.x to v1.x migration introduced breaking changes documented in MIGRATION_GUIDE.md; projects that skip the migration guide often encounter unexpected behavior.

The fetch API as the Built-in Alternative

The fetch API is built into modern browsers and has been available in Node.js since version 18 without a flag. It uses a streaming response model by default, supports HTTP/2 in environments that provide it, and requires no dependencies. The trade-off is that fetch does not automatically convert HTTP error status codes into rejected promises: a 404 or 500 response resolves, not rejects, unless the caller checks response.ok explicitly. Fetch also has no built-in interceptor mechanism; teams that need request transformation or global error handling typically build a thin wrapper. For projects that are starting fresh and do not need interceptors or cross-runtime parity out of the box, the native fetch API is a reasonable starting point before deciding whether Axios adds enough value.

Version History and the v0.x Security Support Situation

Axios maintains two active branches. The v1.x branch, currently at version 1.20.0 (released 2026-08-24), is the primary development line with the v1.x default branch. The v0.x branch, most recently at v0.34.0 (released 2026-09-13), is no longer developed by the core team; it receives security-only support through herodevs under a commercial arrangement, as noted at the top of the README. Teams still on v0.x who want continued security patches beyond what the open-source project provides need to follow the herodevs link. The MIGRATION_GUIDE.md in the repository describes the changes required to move from v0.x to v1.x. The library is MIT-licensed, and the repository includes a THREATMODEL.md that documents the security assumptions the project makes.

Editorial conclusion

Axios is a practical choice for teams maintaining existing codebases that rely on its interceptor API, cancellation support, or need identical HTTP behavior in browser and Node.js from one library. New projects targeting only modern browsers or Node.js 18+ should evaluate whether the native fetch API meets their needs before adding a dependency. Teams migrating from v0.x should read MIGRATION_GUIDE.md before upgrading, since v1.x introduced breaking changes. The v0.x branch receives security-only support from herodevs, not from the core project.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes