Apollo Link Batch HTTP

1.2.14 verified Sat Apr 25 auth: no javascript maintenance

A terminating link for Apollo Client that batches multiple GraphQL operations (queries, mutations) into a single HTTP POST request to reduce network overhead. Current version is 1.2.14, last updated in 2019, and part of the Apollo Link ecosystem. It is in maintenance mode; the successor is the `@apollo/client` core link. Key differentiator: unlike serial requests, it groups operations by configurable batch key, interval (default 10ms), and max count (default 10). Requires `graphql` peer dependency and a `fetch` polyfill for non-browser environments (e.g., `unfetch` or `node-fetch`). Ships TypeScript types. Use only with Apollo Client v2; v3 uses `@apollo/client/link/batch-http`.

Common errors

error Error: fetch is not defined ↓

cause Running in an environment without global fetch (e.g., Node.js <18, older browsers).

fix

Install a polyfill like node-fetch and pass it: new BatchHttpLink({ fetch: require('node-fetch') }).

error TypeError: (intermediate value).concat is not a function ↓

cause Incorrect import: using default import instead of named import.

fix

Use import { BatchHttpLink } from 'apollo-link-batch-http' instead of import BatchHttpLink from....

error Uncaught (in promise) Error: Response not successful: Received status code 400 ↓

cause Server expects non-batch requests but receives batched array; or batch endpoint is misconfigured.

fix

Ensure server supports batch GraphQL (array of queries). Consider setting batchMax: 1 to send individual requests.

Warnings

deprecated apollo-link-batch-http is deprecated in favor of @apollo/client's built-in batch HTTP link. ↓

fix Migrate to `import { BatchHttpLink } from '@apollo/client/link/batch-http'` when upgrading to Apollo Client v3.

gotcha The `batchKey` function defaults to returning the same string for all operations, meaning all operations are batched together regardless of context. This can cause unexpected behavior if you intend separate batches per operation type. ↓

fix Provide a custom `batchKey` function that returns a unique key per operation (e.g., based on operation name or context).

gotcha Batch HTTP link only supports POST method; `fetchOptions.method: 'GET'` will not batch and may cause errors. ↓

fix Avoid setting `fetchOptions.method` to 'GET'. Use `apollo-link-http` for GET requests.

gotcha If you do not provide a `fetch` polyfill in environments without global `fetch` (e.g., Node.js <18, old browsers), the link will throw `fetch is not defined`. ↓

fix Install and pass a fetch polyfill such as `node-fetch` or `unfetch` via `new BatchHttpLink({ fetch: require('node-fetch') })`.

breaking Peer dependency `graphql` must be >=0.11.0 and <=15.0.0; newer versions (e.g., ^16) may cause type or runtime errors. ↓

fix Downgrade `graphql` to a supported version or migrate to `@apollo/client` which supports newer graphql.

Install

npm install apollo-link-batch-http

yarn add apollo-link-batch-http

pnpm add apollo-link-batch-http

Imports

BatchHttpLink
wrong
```
import BatchHttpLink from 'apollo-link-batch-http'
```
correct
```
import { BatchHttpLink } from 'apollo-link-batch-http'
```
Named export, not default. Also available as `require('apollo-link-batch-http').BatchHttpLink` in CJS.
BatchHttpLink (constructor)
wrong
```
new BatchHttpLink('/graphql')
```
correct
```
const link = new BatchHttpLink({ uri: '/graphql' })
```
Options must be passed as an object, not a positional string.

withClientState (if applicable)

wrong

import { withClientState } from 'apollo-link-batch-http'

correct

import { withClientState } from 'apollo-link-state'

`withClientState` is from `apollo-link-state`, not this link.

Quickstart

Creates an Apollo Client with batch HTTP link, configuring max batch size and interval, then executes a query.

import { ApolloClient } from 'apollo-client';
import { InMemoryCache } from 'apollo-cache-inmemory';
import { BatchHttpLink } from 'apollo-link-batch-http';

const link = new BatchHttpLink({
  uri: 'https://api.example.com/graphql',
  batchMax: 5,
  batchInterval: 20,
});

const client = new ApolloClient({
  link,
  cache: new InMemoryCache(),
});

client.query({ query: gql`{ viewer { name } }` }).then(result => console.log(result));