Bundling Axios with Webpack, Rollup, and Vite

Bundling the Axios HTTP client into modern web applications requires addressing module resolution, target environments, dependency polyfills, and bundle size optimization. While Axios is versatile and works in both Node.js and browser environments, differences in how Webpack, Rollup, and Vite process packages mean developers must account for specific configurations to avoid bloated builds or runtime errors.

Module Format and Resolution (ESM vs. CommonJS)

Axios provides both CommonJS and ECMAScript Module (ESM) builds. Modern bundlers rely on the exports field in package.json to determine the correct entry point:

  • ESM Preference: Ensure your bundler resolves the ESM version to allow better static analysis and integration with native module pipelines.
  • Dual-Package Hazard: Importing Axios using mixed syntax (e.g., mixing require('axios') and import axios from 'axios') in large codebases can lead to duplicate instances in the final bundle. Enforce a single import strategy.

Platform Target and Adapter Selection

Axios automatically chooses between two adapters: the Node.js adapter (using http/https modules) and the browser adapter (using XMLHttpRequest or fetch). Bundlers must be instructed which environment is being targeted.

  • Browser Targets: The bundler should resolve the browser entry defined in Axios's package.json. If misconfigured, the bundler may attempt to include Node.js built-in modules (http, https, zlib, stream), causing build failures or unnecessary bloat.
  • Universal/SSR Applications: For frameworks utilizing Server-Side Rendering (like Next.js, Nuxt, or SvelteKit), configure distinct client and server build pipelines so the correct adapter is packaged for each context.

Bundler-Specific Configurations

Webpack

  • Webpack 5 Polyfills: Unlike Webpack 4, Webpack 5 does not automatically polyfill Node.js core modules. If your configuration targets the web platform, ensure your target: 'web' is explicitly set. If Node-specific imports leak into the browser bundle, avoid polyfilling http or https; instead, verify that module resolution is picking the browser bundle.
  • Side Effects: Axios is generally marked as containing side effects due to its default instance creation and interceptor setup. Ensure your Webpack optimization settings do not improperly prune required interceptors.

Rollup

  • Plugin Requirements: Rollup requires @rollup/plugin-node-resolve to locate Axios within node_modules. If using older versions of Axios or CommonJS dependencies, @rollup/plugin-commonjs is also necessary.
  • Browser Field: Enable the browser: true flag in @rollup/plugin-node-resolve to force Rollup to respect the browser field in package.json, ensuring browser-safe code is bundled instead of Node.js adapters.

Vite

  • Dependency Pre-Bundling: Vite automatically pre-bundles dependencies like Axios using esbuild during development. This converts CommonJS dependencies to ESM and caches them. Axios typically works out of the box with Vite.
  • SSR Externalization: When building for SSR, ensure Axios is marked properly in ssr.noExternal or ssr.external depending on whether you want Axios bundled into the server output or resolved at runtime via Node.js.

Bundle Size and Tree-Shaking Considerations

Axios is architected around a single, highly configurable core instance. As a result:

  • Limited Tree-Shaking: Because core functionality (interceptors, transforms, defaults) is attached directly to the axios object and its prototypes, standard tree-shaking will not remove unused HTTP methods (e.g., axios.put or axios.delete).
  • Custom Instances: Creating shared custom instances via axios.create() is recommended for maintainability, but it does not reduce the base footprint of the library.
  • Alternative Lightweight Wrappers: If bundle size is the primary constraint and only basic fetch functionality is required, evaluate whether Axios's advanced features (automatic JSON parsing, request cancellation, interceptors) justify its weight compared to native fetch.