Apollo HTTP Link

Common errors

• ReferenceError: fetch is not defined

  cause The runtime environment (e.g., Node.js or older browser) does not natively support the `fetch` API, which `apollo-link-http` requires.
  fix Install and provide a `fetch` polyfill. For Node.js, install `node-fetch` (`npm install node-fetch`) and pass it to the link: `import fetch from 'node-fetch'; const link = createHttpLink({ uri: '/graphql', fetch });`.

• Error: Network error: Failed to fetch

  cause Generic network error often due to incorrect URI, server being down, CORS issues, or firewall blocking the request.
  fix Verify the `uri` option points to a valid and accessible GraphQL endpoint. Check browser console for CORS errors. Ensure the GraphQL server is running and accessible from the client's network location. Temporarily disable security software if testing locally.

• GraphQL error: Must provide document

  cause This error typically originates from the GraphQL server, indicating it received an empty or invalid GraphQL request, often a symptom of an issue with how the query or mutation is being sent by the client, or a malformed request body.
  fix Ensure that your `ApolloClient` instance is correctly configured with a cache and a link. Verify that the GraphQL query or mutation string is valid and being passed correctly to `client.query()` or `client.mutate()`. If using `GET` for queries, ensure the query parameters are not exceeding URL length limits.

Warnings

• breaking This package is part of the older `apollo-link` ecosystem. For new projects or when upgrading Apollo Client to v3 or higher, it is highly recommended to use the built-in HTTP link directly from `@apollo/client/link/http` instead of `apollo-link-http` to avoid potential compatibility issues and leverage modern features.
  Fix: Migrate to `import { HttpLink } from '@apollo/client/link/http';` and instantiate using `new HttpLink({ uri: '/graphql' });`.
• gotcha The `apollo-link-http` relies on a global `fetch` API. In environments like Node.js or older browsers that lack native `fetch`, you must provide a polyfill or custom `fetch` implementation via the `fetch` option during link creation.
  Fix: For Node.js, use `node-fetch`: `import fetch from 'node-fetch'; const link = createHttpLink({ uri: '/graphql', fetch });`. For older browsers, use `unfetch` or a similar polyfill.
• gotcha Setting `fetchOptions.method: 'GET'` on the link's options or via context will force *all* requests (queries and mutations) to use GET. To only use GET for queries while keeping mutations as POST, use the `useGETForQueries: true` option at the top level.
  Fix: If only queries should use GET, set `createHttpLink({ uri: '/graphql', useGETForQueries: true })`. If all requests should be GET, `createHttpLink({ uri: '/graphql', fetchOptions: { method: 'GET' } })` is acceptable, but be aware of GraphQL HTTP GET specification limitations for complex queries.
• gotcha Values provided in the `context` object (e.g., `context.headers`, `context.credentials`, `context.uri`, `context.fetchOptions`) will override any corresponding options initially set when creating the `HttpLink` instance. This is a powerful feature but can lead to unexpected behavior if not managed carefully, especially in multi-link chains.
  Fix: Be explicit about where dynamic options are set. For per-request dynamic values, use `apollo-link-context` to merge or override options into the context before the HTTP link processes them. For global defaults, set them directly on `createHttpLink`.

Install

• npm install apollo-link-http npm
• yarn add apollo-link-http yarn
• pnpm add apollo-link-http pnpm

Imports

• createHttpLink
  wrong:

  const { createHttpLink } = require('apollo-link-http');

  correct:

  import { createHttpLink } from 'apollo-link-http';

  Primary factory function. While CommonJS `require` might technically work in older Node.js setups, modern Apollo Link usage strongly favors ESM imports.
• HttpLink

  import { HttpLink } from 'apollo-link-http';

  The class from which `createHttpLink` instantiates. Less commonly imported directly than `createHttpLink`.

Quickstart

Demonstrates initializing `apollo-link-http` and integrating it with Apollo Client, including dynamic headers.

import { ApolloClient, InMemoryCache } from '@apollo/client';
import { createHttpLink } from 'apollo-link-http';
import { setContext } from '@apollo/client/link/context';

// Configure the HTTP link
const httpLink = createHttpLink({
  uri: process.env.GRAPHQL_URI ?? '/graphql',
});

// Optionally, add an auth link to set headers dynamically
const authLink = setContext((_, { headers }) => {
  // get the authentication token from local storage if it exists
  const token = localStorage.getItem('token');
  // return the headers to the context so httpLink can read them
  return {
    headers: {
      ...headers,
      authorization: token ? `Bearer ${token}` : "",
    }
  }
});

// Initialize Apollo Client with the composed link and a cache
const client = new ApolloClient({
  link: authLink.concat(httpLink),
  cache: new InMemoryCache()
});

// Example query using the client (requires @apollo/client to be installed)
// import { gql } from '@apollo/client';
// client.query({
//   query: gql`
//     query GetDogs {
//       dogs {
//         id
//         breed
//       }
//     }
//   `
// }).then(result => console.log(result.data));