Codakey
Play
← Back to mzabriskie/axios

How to Deploy & Use mzabriskie/axios

Axios HTTP Client - Deployment & Usage Guide

1. Prerequisites

Runtime Requirements

  • Node.js: v12.x or higher (v18+ recommended for HTTP/2 support)
  • npm: v6.x or higher (or Yarn v1.22+/v3+)
  • Git: v2.x or higher

Browser Support

  • Modern browsers with Fetch API support (Chrome 42+, Firefox 39+, Safari 10.1+, Edge 14+)
  • For legacy browsers: XMLHttpRequest fallback (automatic)

Development Tools (for contributors)

  • TypeScript (if modifying type definitions)
  • Rollup (bundler, installed via npm)

2. Installation

As a Project Dependency

# Using npm
npm install axios

# Using yarn
yarn add axios

# Using pnpm
pnpm add axios

For Development/Contribution

# Clone the repository
git clone https://github.com/axios/axios.git
cd axios

# Install dependencies
npm install

# Verify installation
npm test

Browser CDN (No Build Step)

<!-- Latest version -->
<script src="https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js"></script>

<!-- Specific version -->
<script src="https://unpkg.com/axios@1.6.0/dist/axios.min.js"></script>

3. Configuration

Environment Variables (Node.js)

Axios automatically respects standard proxy environment variables (via proxy-from-env):

# HTTP/HTTPS proxy configuration
HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080
NO_PROXY=localhost,127.0.0.1,.internal.company.com

# SSL/TLS settings
NODE_TLS_REJECT_UNAUTHORIZED=0  # Only for development/testing

Basic Instance Configuration

import axios from 'axios';

// Create configured instance
const client = axios.create({
  baseURL: 'https://api.example.com',
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  // Enable HTTP/2 if supported (Node.js only)
  http2: true,
  // Decompression settings
  decompress: true,
  // Proxy configuration (overrides env vars)
  proxy: {
    protocol: 'http',
    host: '127.0.0.1',
    port: 9000,
    auth: {
      username: 'user',
      password: 'pass'
    }
  }
});

Adapter Selection

// Force specific adapter
const response = await axios.get('https://api.example.com/data', {
  adapter: 'http',    // Node.js native http/https
  // or
  adapter: 'fetch',   // Browser Fetch API
});

4. Build & Run

For Library Contributors

# Install dependencies
npm install

# Build distribution files (ESM, CJS, UMD)
npm run build

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Type check TypeScript definitions
npm run test:types

# Watch mode for development
npm run dev

Output Structure

After build:

dist/
├── axios.js          # UMD bundle for browsers
├── axios.min.js      # Minified UMD
├── axios.cjs         # CommonJS for Node.js
├── esm/              # ES modules
│   ├── axios.js
│   └── axios.min.js

Local Testing

# Link local axios for testing in other projects
npm link

# In your test project
npm link axios

5. Deployment

Publishing to npm (Maintainers)

# 1. Update version
npm version patch|minor|major

# 2. Build distribution
npm run build

# 3. Run full test suite
npm run test:all

# 4. Publish
npm publish

# For beta/alpha releases
npm publish --tag next

Using in Production Applications

Node.js Server:

// server.js
import axios from 'axios';

// Configure global defaults
axios.defaults.timeout = 30000;
axios.defaults.headers.common['User-Agent'] = 'MyApp/1.0';

// Handle global errors
axios.interceptors.response.use(
  response => response,
  error => {
    console.error('API Error:', error.message);
    return Promise.reject(error);
  }
);

Browser Application:

// Import specific adapter if needed
import axios from 'axios/lib/adapters/fetch.js'; // Force fetch adapter

// Or standard import (auto-detects environment)
import axios from 'axios';

Bundling Considerations:

  • Webpack/Vite/Rollup: Tree-shaking supported for ESM imports
  • Server-Side Rendering: Ensure http adapter is used server-side, fetch client-side
  • Edge Functions: Use fetch adapter for Vercel Edge, Cloudflare Workers, Deno Deploy

Docker Deployment

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

Important: In containers, ensure HTTP_PROXY/HTTPS_PROXY env vars are passed if behind corporate firewalls.

6. Troubleshooting

Common Issues

Module Resolution Errors (ESM vs CommonJS)

// If "require is not defined" in ESM context:
import axios from 'axios';

// If using CommonJS:
const axios = require('axios').default || require('axios');

Proxy Not Working (Node.js)

  • Verify HTTP_PROXY env var is set (not lowercase http_proxy)
  • Check NO_PROXY includes internal domains
  • For authenticated proxies, ensure URL encoding: http://user:p%40ss@proxy:8080

HTTP/2 Connection Issues

// Disable HTTP/2 if encountering ERR_HTTP2_STREAM_CANCEL errors
const client = axios.create({
  http2: false  // Force HTTP/1.1
});

SSL/TLS Certificate Errors

// Development only - do not use in production
const agent = new https.Agent({  
  rejectUnauthorized: false
});
axios.defaults.httpsAgent = agent;

Request Timeout on Large Files

// Increase timeout for uploads/downloads
axios.post('/upload', formData, {
  timeout: 0,  // No timeout
  onUploadProgress: (progressEvent) => {
    const percentCompleted = Math.round((progressEvent.loaded * 100) / progressEvent.total);
    console.log(percentCompleted);
  }
});

Browser CORS Errors

  • Ensure server sends Access-Control-Allow-Origin headers
  • For preflight requests, server must handle OPTIONS method
  • Credentials mode: axios.defaults.withCredentials = true

Memory Leaks in Long-Running Node.js Processes

  • Ensure response streams are consumed or destroyed
  • Use responseType: 'stream' for large files and pipe to destination
  • Clear interceptors when no longer needed: axios.interceptors.request.eject(id)

Debug Logging

# Enable debug output
DEBUG=axios* node app.js

# Or in browser console
localStorage.debug = 'axios*'

Getting Help

← Project overviewView alternatives to mzabriskie/axios →