axios/AGENTS.md

AGENTS.md

axios is a promise-based HTTP client for the browser and Node.js. The default instance is exported from lib/axios.js via index.js. Browser builds use the XHR or Fetch adapter; Node uses the HTTP/HTTPS adapter. Platform selection lives in lib/platform/.

This file is the canonical contributor guide for both human and AI agents working in this repo. .github/copilot-instructions.md is a thin stub that points back here — keep it in sync with the load-bearing safety rules below if you change them.

Setup And Safety

• Use npm ci; repo .npmrc sets ignore-scripts=true, and CI also uses npm ci --ignore-scripts.
• Do not remove ignore-scripts=true; if git hooks are needed after a fresh install, run npm rebuild husky && npx husky once.
• Adding or updating dependencies is security-sensitive; package-lock.json is checked by lockfile-lint for npm HTTPS hosts and integrity hashes.
• Build/test/lint tools still execute dependency code despite ignore-scripts; avoid unnecessary full builds when a focused check proves the change.
• Do not add new runtime dependencies without discussion; the dependency surface is intentionally tiny.

Commands

• Build published artifacts: npm run build (gulp clear deletes dist/, then Rollup writes browser ESM/UMD/CJS and Node CJS bundles).
• Lint source only: npm run lint; focused lint: npx eslint lib/path/to/file.js.
• Unit tests: npm run test:vitest:unit; focused unit test: npm run test:vitest:unit -- tests/unit/path.test.js.
• Browser tests need Playwright installed first (npx playwright install locally; CI uses npx playwright install --with-deps); run npm run test:vitest:browser:headless for CI parity.
• Smoke/module compatibility suites test the packed package, not the source tree: run npm run build, npm pack, install the tarball into the relevant tests/smoke/* or tests/module/* package, then run that suite's npm script.
• CI order is install -> build -> Playwright install -> unit -> browser headless -> pack -> CJS/ESM module and smoke tests -> Bun/Deno smoke tests.

Package Shape

• Source is ESM (type: module); public ESM entry is index.js, which re-exports the default instance from lib/axios.js.
• Do not edit dist/ by hand; it is ignored and generated from lib/ by Rollup.
• Runtime package exports are split by environment: browser/react-native map Node HTTP/platform files to browser/null replacements, while Node CJS ships as dist/node/axios.cjs.
• Keep public runtime exports, index.d.ts (ESM types), and index.d.cts (CJS export = axios types) in sync for API changes.
• lib/env/data.js is version-generated by gulp version; do not edit it for normal feature work.

Architecture Boundaries

• lib/core/ is axios domain logic: request dispatch, config merge, interceptors, headers, errors. Key classes: Axios (request dispatch + interceptor chains), AxiosError (standardized error codes), AxiosHeaders (case-insensitive header normalization), InterceptorManager (sync/async interceptor registration).
• lib/adapters/ performs I/O; default adapter preference is ['xhr', 'http', 'fetch'], with capability selection in lib/adapters/adapters.js. Detect by capability, not environment name.
• lib/platform/ selects Node by default; browser builds rely on package/rollup aliasing to lib/platform/browser.
• lib/helpers/ should stay generic and reusable outside axios; do not put axios-specific request lifecycle logic there.
• New lib/**/*.js files should match existing source style: ESM imports with explicit .js extensions, 'use strict'; where current library files use it, and AxiosError for axios-originated failures.

Naming Conventions

• Classes: PascalCase (Axios, AxiosError, InterceptorManager).
• Functions: camelCase (buildURL, mergeConfig, dispatchRequest).
• Error codes: UPPER_SNAKE_CASE constants on AxiosError (ERR_NETWORK, ETIMEDOUT).
• Internal class slots: Symbol-keyed (e.g. const $internals = Symbol('internals') in lib/core/AxiosHeaders.js) rather than underscore-prefixed properties.

Error Handling

• Throw AxiosError for axios-originated failures; never raw Error. Pass (message, code, config, request, response) so consumers can introspect.
• Wrap third-party errors with AxiosError.from(error, code, config, request, response).
• Canonical code list lives in lib/core/AxiosError.js; current codes include ERR_BAD_OPTION_VALUE, ERR_BAD_OPTION, ECONNABORTED, ETIMEDOUT, ECONNREFUSED, ERR_NETWORK, ERR_FR_TOO_MANY_REDIRECTS, ERR_DEPRECATED, ERR_BAD_RESPONSE, ERR_BAD_REQUEST, ERR_CANCELED, ERR_NOT_SUPPORT, ERR_INVALID_URL, ERR_FORM_DATA_DEPTH_EXCEEDED.
• Validate config options through the validator helper; do not invent ad-hoc validation paths.

Interceptor Execution Order

• Request interceptors run last-registered-first (LIFO).
• Response interceptors run first-registered-first (FIFO).
• Both support synchronous: true (avoids Promise wrapping when no async handler is in the chain) and runWhen: (config) => boolean for conditional execution.
• Order matters for both behavior and tests; document it when adding new built-in interceptors.

Request Lifecycle

1. User calls axios() or a method alias.
2. Merge instance defaults with request config via mergeConfig.
3. Run request interceptors (LIFO).
4. Select adapter via lib/adapters/adapters.js capability check.
5. Apply transformRequest functions.
6. Adapter performs the HTTP request.
7. Apply transformResponse functions.
8. Run response interceptors (FIFO).
9. Resolve promise with AxiosResponse or reject with AxiosError.

Cancellation

• Both CancelToken (legacy) and AbortSignal (modern) are supported simultaneously; do not break either path.
• Cancellation must work at any lifecycle stage, including mid-flight body reads.
• Always remove signal listeners on settlement or cancellation to prevent memory leaks.

Common Pitfalls

• Do not mutate config objects in-place; return new objects from merges/transforms.
• Do not assume browser- or Node-specific globals exist; capability-check first.
• Do not use Function.prototype.bind directly — use lib/helpers/bind.js, which forwards arguments via apply and is what the rest of the library relies on.
• Do not throw raw Error from library code; use AxiosError with an appropriate code (see Error Handling).

Tests

• Test layout is runtime-first: tests/unit/**/*.test.js, tests/browser/**/*.browser.test.js, tests/smoke/esm/**/*.smoke.test.js, tests/smoke/cjs/**/*.smoke.test.cjs.
• Use tests/setup/server.js for local HTTP servers and cleanup with try/finally; leaking servers causes Vitest hangs.
• Keep CJS and ESM smoke coverage aligned when behavior is packaging/import related.
• Type compatibility is exercised through tests/module/cjs with TypeScript 4.9 and tests/module/esm with TypeScript 5.x; run the matching module suite for declaration changes.
• Browser tests replace globals such as XHR; restore globals and reset spies in cleanup hooks.

Security-Sensitive Code

• For config reads that affect behavior, do not use prototype-walking reads (in, destructuring, or direct config.foo on untrusted config); guard with own-property checks as in utils.hasOwnProp / local own() helpers.
• New merge or object materialization code must continue filtering __proto__, constructor, and prototype; regressions here are security bugs.
• Changes touching URL construction, redirects, proxy/env handling, XSRF, socket paths, decompression limits, or adapters should consult THREATMODEL.md and add focused regression tests.
• Keep withXSRFToken cross-origin behavior explicit: only true forces cross-origin XSRF header attachment.
• Do not weaken beforeRedirect, proxy, or socketPath safeguards without tests covering credential leakage or SSRF-style cases.