Promise based HTTP client for the browser and node.js

All Features

• Make fetch() requests from the browser
• Make http requests from Node.js
• Auto environment detection
• Supports the Promise API
• Intercept request and response
• Conditional interceptors (runWhen)
• Synchronous interceptors
• Transform request and response data
• Cancel requests via AbortController
• Timeouts with native AbortSignal
• Query parameter serialization
• Automatic JSON serialization
• Automatic multipart/form-data serialization
• Automatic x-www-form-urlencoded serialization
• Advanced FormData (dots, indexes, metaTokens)
• Client-side XSRF protection
• Upload and download progress tracking
• Rate limiting (maxRate)
• Max content length / body length limits
• Configurable max redirects
• Exponential backoff retry
• Per-method default headers
• Transitional options
• Config env for polyfill injection
• Custom adapter support
• First-class TypeScript generics
• HTTP/2 support (httpVersion: 2)
• Basic Auth (auth config)
• Proxy support (Node.js)
• httpAgent / httpsAgent
• postForm / putForm / patchForm
• all() / spread() / isCancel()
• getUri() / toFormData() / formToJSON()
• beforeRedirect hook
• socketPath for Unix sockets
• responseType: 'document'

Comparison

Installing

Using npm:

Using yarn:

Examples

GET request

import fetchgo from 'fetch-go';

// GET with typed response
const { data } = await fetchgo.get<User[]>('/api/users');

// With query params
const { data } = await fetchgo.get('/api/users', {
  params: { page: 1, limit: 10 }
});

POST request

const { data } = await fetchgo.post('/api/users', {
  name: 'John',
  email: 'john@example.com'
});

Per-method headers

const api = fetchgo.create({
  baseURL: 'https://api.example.com',
  headers: {
    common: { 'Accept': 'application/json' },
    get:    { 'Cache-Control': 'no-cache' },
    post:   { 'Content-Type': 'application/json' },
  }
});

Smart Interceptors

api.interceptors.request.use(
  (config) => {
    config.headers['X-Auth'] = getToken();
    return config;
  },
  undefined,
  {
    // Only run for /api/ routes
    runWhen: (config) => config.url?.startsWith('/api/'),
    // Run synchronously (no await)
    synchronous: true,
  }
);

Rate Limiting

// Limit download to 100 KB/s
await fetchgo.get('/large-file', {
  maxRate: 100 * 1024,
  onDownloadProgress: (e) => {
    console.log(`${Math.round(e.progress * 100)}%`);
  }
});

// Separate upload/download rates
await fetchgo.post('/upload', file, {
  maxRate: [50 * 1024, 200 * 1024], // [upload, download]
});

Advanced FormData

import { toFormData } from 'fetch-go';

// Dot notation for nested keys
toFormData({ user: { name: 'John' } }, undefined, { dots: true });
// → user.name = 'John'

// Array index modes
toFormData({ tags: ['a', 'b'] }, undefined, { indexes: true });
// → tags[0]=a, tags[1]=b

Parallel Requests

// fetchgo.all() + fetchgo.spread()
const [users, posts] = await fetchgo.all([
  fetchgo.get('/api/users'),
  fetchgo.get('/api/posts'),
]);

Transitional Options

const api = fetchgo.create({
  transitional: {
    silentJSONParsing: true,    // Don't throw on bad JSON
    forcedJSONParsing: false,   // Force JSON parse
    clarifyTimeoutError: true, // ETIMEDOUT code
  }
});

Error Handling

import { FetchGoError, isCancel } from 'fetch-go';

try {
  await api.get('/might-fail');
} catch (error) {
  if (fetchgo.isCancel(error)) {
    console.log('Cancelled!');
  } else if (error instanceof FetchGoError) {
    console.log(error.status);       // 404
    console.log(error.response?.data);// { message: "Not Found" }
    console.log(error.code);         // "ERR_BAD_REQUEST"
  }
}

Migrate from Axios

// Just change the import — everything else works!
- import axios from 'axios';
+ import fetchgo from 'fetch-go';

- const api = axios.create({ baseURL: '...' });
+ const api = fetchgo.create({ baseURL: '...' });

const { data } = await api.get('/users');