gaxios is an HTTP client library meticulously designed for seamless integration with Google APIs and services, providing a familiar `axios`-like interface built on top of `node-fetch`. It facilitates robust HTTP request management in both Node.js and browser environments. The current stable version, 7.1.4, is actively maintained as part of the broader `google-cloud-node-core` monorepo. This integration means its release cadence is often synchronized with updates to other Google client libraries, leading to frequent releases driven by bug fixes, dependency updates, and feature enhancements within the Google ecosystem. Key differentiators include its explicit optimization for Google's API patterns, a developer-friendly `axios`-like API, and an alternative `fetch`-compatible API for wider browser and modern Node.js compatibility. The package ships with comprehensive TypeScript types, ensuring a strong development experience in TypeScript projects. It officially supports Node.js environments version 18 and above.
npm install gaxiosVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates basic GET and POST requests using the default `request` function and a custom `Gaxios` instance, including setting base URLs, headers, and handling timeouts and errors.
Upgrade your Node.js runtime to version 18 or higher. Alternatively, pin gaxios to a compatible version (e.g., `npm install gaxios@6`) if a Node.js upgrade is not feasible.
Ensure your project uses ES Modules (`import/export`) for gaxios or configure your environment (e.g., `package.json` `"type": "module"`) to handle ESM correctly. For existing CommonJS projects, consider using dynamic `import()` or stick to an older version of gaxios if module type conversion is not an option.
Be mindful when setting `gaxios.defaults.headers.Authorization` or similar authentication headers. If you intend to use `google-auth-library` or other authentication mechanisms, ensure that your custom defaults do not inadvertently override them. Prefer passing authentication details per-request if defaults are broad.
To prevent unbounded memory usage, set `maxContentLength` to a sensible byte limit (e.g., `10 * 1024 * 1024` for 10MB) in your `GaxiosOptions` if you are expecting potentially large responses.
To receive the response body as a stream, set `responseType: 'stream'` in your `GaxiosOptions`. This will make the `res.data` property a `ReadableStream` (in browsers) or `stream.Readable` (in Node.js).
Convert your module to ES Module syntax using `import { symbol } from 'gaxios';` and ensure your `package.json` has `"type": "module"` or your file ends with `.mjs`.Verify network connectivity, check for proxy configurations, ensure the target URL is correct and accessible, and confirm that firewalls are not blocking outbound connections from your application.
Ensure all related dependencies (gaxios, teeny-request, proxy agents) are updated to their latest compatible versions, as this often indicates an incompatibility between versions of underlying networking libraries. If explicitly using an agent, check its documentation for updated instantiation patterns.
Explicitly set the `Content-Type` header in your `GaxiosOptions` (e.g., `headers: { 'Content-Type': 'application/x-www-form-urlencoded' }`) when the target API expects a format other than JSON for object payloads. For `URLSearchParams`, pass an instance of `URLSearchParams` to `data`.No dependency data recorded yet.