axios/AGENTS.md

AGENTS.md

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.

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.
• lib/adapters/ performs I/O; default adapter preference is ['xhr', 'http', 'fetch'], with capability selection in lib/adapters/adapters.js.
• 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.

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.