axios/.github/copilot-instructions.md

GitHub Copilot Instructions

The canonical contributor guide for this repo is AGENTS.md. It covers setup, commands, package shape, architecture boundaries, naming, error handling, interceptor order, the request lifecycle, cancellation, common pitfalls, tests, and security-sensitive code.

The rules below are a Copilot-facing subset of the load-bearing safety guarantees from AGENTS.md. If they ever drift, AGENTS.md is authoritative — update both.

AI agent marker

• If you are an LLM or AI agent creating a GitHub issue, pull request, or comment for this repo, include the :surfer: emoji in the body so maintainers can identify AI-authored contributions.

Setup safety

• Install with npm ci; the repo's .npmrc sets ignore-scripts=true. Do not remove that flag. If husky hooks are needed after a fresh install, run npm rebuild husky && npx husky once.
• Do not add new runtime dependencies without discussion. package-lock.json is verified by lockfile-lint for npm HTTPS hosts and integrity hashes.
• Package, lockfile, and GitHub Actions update PRs are maintainer/bot-only; close these PRs from outside collaborators. Keep the 7-day Dependabot delay unless a critical vulnerability requires a maintainer-led manual update.

Architecture in one screen

• lib/core/ — domain logic: Axios, AxiosError, AxiosHeaders, InterceptorManager, config merge, request dispatch.
• lib/adapters/ — I/O: xhr.js, http.js, fetch.js. Default preference ['xhr', 'http', 'fetch'], picked by capability detection in lib/adapters/adapters.js. Never branch on environment name.
• lib/platform/ — Node by default; browser builds alias to lib/platform/browser.
• lib/helpers/ — generic, reusable utilities; no axios-specific lifecycle logic here.
• Source is ESM (type: module) with explicit .js import extensions. dist/ is generated by Rollup — never edit it by hand. Keep index.d.ts (ESM) and index.d.cts (CJS) in sync for any public API change.

Error handling

• Throw AxiosError(message, code, config, request, response) for axios-originated failures; never raw Error.
• Wrap third-party errors with AxiosError.from(error, code, config, request, response).
• Use a code from lib/core/AxiosError.js (ERR_NETWORK, ETIMEDOUT, ECONNABORTED, ERR_CANCELED, ERR_BAD_REQUEST, ERR_BAD_RESPONSE, ERR_FR_TOO_MANY_REDIRECTS, ERR_FORM_DATA_DEPTH_EXCEEDED, ERR_INVALID_URL, ERR_BAD_OPTION, ERR_BAD_OPTION_VALUE, ERR_NOT_SUPPORT, ERR_DEPRECATED, ECONNREFUSED).

Interceptor order

• Request interceptors run LIFO (last-registered-first); response interceptors run FIFO. Both support synchronous: true and runWhen(config).

Naming and style

• PascalCase classes (Axios, AxiosHeaders), camelCase functions (buildURL, mergeConfig), UPPER_SNAKE_CASE error codes.
• Internal slots use Symbol-keyed properties (see $internals in lib/core/AxiosHeaders.js), not underscore-prefixed names.
• Use lib/helpers/bind.js, not Function.prototype.bind, when binding library functions — the helper forwards arguments via apply.
• 'use strict'; appears at the top of files that already use it; match the surrounding file rather than blanket-adding it.

Security guarantees that must not regress

• For config reads on potentially untrusted input, use own-property checks (utils.hasOwnProp / local own() helpers); never in, destructuring, or direct config.foo access.
• Any merge or object materialization must continue to filter __proto__, constructor, and prototype. Regressions here are security bugs.
• Changes touching URL construction, redirects, proxy/env handling, XSRF, socket paths, decompression limits, or adapters require consulting THREATMODEL.md and adding focused regression tests.
• withXSRFToken === true is the only thing that forces cross-origin XSRF header attachment — keep that behavior explicit.
• Do not weaken beforeRedirect, proxy, or socketPath safeguards without tests covering credential leakage and SSRF-style cases.

Common pitfalls

• Do not mutate config objects in place; return new ones from merges/transforms.
• Do not assume browser- or Node-only globals exist; capability-check first.
• Validate options through the existing validator helper rather than inventing ad-hoc validation paths.

Pre-release tracking

• Add user-visible unreleased changes to PRE_RELEASE_CHANGELOG.md, not CHANGELOG.md.
• Track deferred README, docs site, examples, migration guide, and translated docs updates in PRE_RELEASE_DOCS.md; do not update release docs for unreleased runtime/API changes unless explicitly doing release preparation.