Axios v0.x vs v1.x Architectural Differences

This article provides an overview of the major architectural and functional differences between Axios v0.x and Axios v1.x. It details the transition from legacy, bespoke patterns to modern web standards, including native ECMAScript Module (ESM) support, a standardized adapter pipeline, built-in TypeScript typings, and modern cancellation handling using standard Web APIs.

1. Modernized Module System and Native ESM Support

Axios v0.x was built primarily as a CommonJS (CJS) library with UMD wrappers for browser environments. This legacy bundling often led to bundling issues, tree-shaking failures, and module resolution friction in modern build tools like Vite, Rollup, and native Node.js ESM environments.

Axios v1.x introduced full dual-package support using the standard exports map in package.json. It provides native ECMAScript Modules (import) alongside CommonJS (require) builds. This architectural shift ensures seamless execution in both Node.js native ESM setups and modern browser bundlers without relying on synthetic default imports or custom polyfills.

2. Standardization on AbortController for Cancellation

In Axios v0.x, request cancellation relied on a proprietary CancelToken API based on a deprecated ECMAScript proposal. This required developers to instantiate custom cancel tokens and manage cancel sources specific only to Axios.

Axios v1.x standardized request cancellation by adding first-class support for the native AbortController and AbortSignal APIs. While CancelToken was retained for backward compatibility, AbortSignal is now the primary mechanism for aborting requests:

const controller = new AbortController();

axios.get('/api/data', {
  signal: controller.signal
});

// Cancel the request
controller.abort();

This aligns Axios with the native Fetch API and standard browser and Node.js runtime specifications.

3. Native TypeScript Architecture

Axios v0.x originally bundled external or manually maintained TypeScript definition files that frequently had synchronization issues with the underlying JavaScript implementation. Typing for configurations, custom instances, and interceptors was often brittle or required extensive type casting.

Axios v1.x completely overhauled its TypeScript architecture. The typings are natively integrated into the core codebase, offering:

  • Strict typing for generic response data structures (axios.get<T>()).
  • Strongly typed interceptor managers.
  • Improved inference for custom headers, HTTP methods, and status codes.
  • Granular type definitions for custom adapters and internal configuration objects.

4. Overhauled Adapter Architecture

Axios abstracts HTTP communication through adapters—using the http module in Node.js and XMLHttpRequest in browsers. In v0.x, these adapters were tightly coupled with the core request dispatching logic, making it difficult to write custom adapters or modify transport behaviors.

In v1.x, the adapter pipeline was refactored:

  • Decoupled Execution: Adapters receive a clean, normalized configuration object and return standard Axios promises.
  • Custom Adapters: Defining and swapping custom adapters (such as custom Fetch-based adapters, Cloudflare Workers transports, or Web Worker adapters) is officially supported and straightforward via the adapter configuration array or function.
  • Stream Handling: Node.js stream management and browser stream parsing were normalized to ensure consistent payload handling across environments.

5. Automated FormData and Multipart Handling

Handling multipart/form-data in Axios v0.x required manually appending values to a browser FormData instance or manually configuring the third-party form-data package with custom header calculations in Node.js.

Axios v1.x introduced built-in automatic serialization for FormData and plain JavaScript objects containing files or binary streams:

  • Automatically detects JavaScript objects with file-like structures or native FormData instances.
  • Sets appropriate Content-Type headers with boundaries automatically.
  • Serializes nested objects and arrays to form structures without requiring manual boundary configurations.

6. Standardized AxiosError Class and Error Serialization

Error handling in v0.x produced error objects with inconsistent property names across browser and Node.js environments.

Axios v1.x standardized the AxiosError class hierarchy:

  • Guarantees standardized properties: code, config, request, response, and status.
  • Implements AxiosError.from() to safely normalize unknown caught exceptions into valid AxiosError instances.
  • Implements standard .toJSON() serialization methods, enabling reliable logging in structured loggers (e.g., Winston, Pino, or Datadog) without losing the HTTP stack trace or response payload.