GraphQL over HTTP Protocol Implementation

Common errors

• ERR_REQUIRE_ESM: require() of ES Module ... not supported

  cause Attempting to use `require()` to import `graphql-http` or its adapter modules in a CommonJS context, while `graphql-http` is primarily an ESM package.
  fix Ensure your project is configured for ESM (add `"type": "module"` to `package.json` or use `.mjs` file extensions for source files) and use `import` statements: `import { createHandler } from 'graphql-http/lib/use/express';`.

• TypeError: Cannot read properties of undefined (reading 'query')

  cause The HTTP framework (e.g., Express, Koa, Fastify) is not parsing the request body before `graphql-http` attempts to access it, typically occurring with POST requests carrying GraphQL queries in the body.
  fix Add appropriate body parsing middleware *before* the `graphql-http` handler. For Express: `app.use(express.json());`. For Koa (as indicated by a v1.22.2 fix), ensure `koa-body` or similar is used correctly and the handler receives the parsed body via `ctx.request.body`.

• Error: Must provide document. | GraphQL schema is not valid.

  cause The `schema` object provided to `createHandler` is either `undefined`, `null`, or not a valid `GraphQLSchema` instance from the `graphql` library, indicating an issue with schema definition or import.
  fix Verify that the `graphql` peer dependency is installed and that the `schema` object passed to `createHandler` is a correctly instantiated `GraphQLSchema` from the `graphql` package. Double-check your `graphql` package version for compatibility with `graphql-http`.

Warnings

• breaking Internal utilities `makeResponse`, `getAcceptableMediaType`, and `isResponse` were explicitly removed from public export in v1.20.0. Code directly importing these internal helpers will break.
  Fix: Avoid importing internal utilities. The library's public API is designed around `createHandler` and its options. If specific response manipulation is needed, consider intercepting the HTTP response object directly via your framework.
• gotcha As of v1.17.1, file extensions were added to imports/exports in ESM type definitions to improve compatibility with Node.js ESM resolution and bundlers. Older TypeScript configurations or bundlers might encounter 'module not found' errors if they do not correctly resolve `.js` extensions for ESM imports.
  Fix: Ensure your `tsconfig.json` targets `es2020` or higher and has `moduleResolution` set to `bundler` or `nodenext`. Explicitly use `.js` extensions in your `import` statements if facing resolution issues (e.g., `import { createHandler } from 'graphql-http/lib/use/express.js'`).
• gotcha `graphql-http` has a peer dependency on the `graphql` library (typically `graphql@^15.0.0` or `graphql@^16.0.0`, but check `peerDependencies` in `package.json`). Using an incompatible version of `graphql` can lead to runtime errors or unexpected behavior due to API mismatches.
  Fix: Install a `graphql` package version that satisfies the peer dependency range for your `graphql-http` version (e.g., `npm install graphql@'^16.0.0'` or `yarn add graphql@'^16.0.0'`). Always verify the specific `peerDependencies` in the `package.json` for the `graphql-http` version you are using.
• gotcha When using `graphql-http` with frameworks like Express or Fastify, you must ensure that the request body is correctly parsed *before* the `graphql-http` handler processes it. `graphql-http` expects the raw request body data to be available, typically as JSON for POST requests.
  Fix: For Express, use `app.use(express.json())` before defining your GraphQL route. For other frameworks, refer to their documentation for body parsing middleware (e.g., `@fastify/formbody` for Fastify if handling `application/x-www-form-urlencoded` or direct content type parsers for JSON).

Install

• npm install graphql-http npm
• yarn add graphql-http yarn
• pnpm add graphql-http pnpm

Imports

• createHandler
  wrong:

  const { createHandler } = require('graphql-http/lib/use/express');

  correct:

  import { createHandler } from 'graphql-http/lib/use/express';

  This is the primary server-side import for integrating with specific HTTP frameworks like Express. The package is ESM-first, so CommonJS `require` is not supported for modern versions. Importing `createHandler` directly from `graphql-http` (the root) will give you a generic handler, not the framework-specific adapter.
• createHandler
  wrong:

  import { createHandler } from 'graphql-http/lib/use/http';

  correct:

  import { createHandler } from 'graphql-http';

  This imports the generic `createHandler` from the core `graphql-http` package. While it can be used, for native Node.js `http` or `https` server integration, it's often more convenient to import from `graphql-http/lib/use/http` for pre-adapted request/response handling.
• createClient
  wrong:

  import { createClient } from 'graphql-http/lib/client';

  correct:

  import { createClient } from 'graphql-http';

  The `createClient` function, used for creating a GraphQL over HTTP client, is directly exported from the root `graphql-http` package for convenience.
• parseRequestParams
  wrong:

  import { parseRequestParams } from 'graphql-http';

  correct:

  import { parseRequestParams } from 'graphql-http/lib/parse';

  This utility function, exposed since v1.22.0, allows manual parsing of HTTP request data into GraphQL operation parameters. It is imported from its specific utility path.

Quickstart

This quickstart sets up a basic GraphQL server using `graphql-http` with Express, defining a simple schema, and demonstrating how to integrate the `createHandler` along with essential body parsing middleware and an optional request context.

import { GraphQLSchema, GraphQLObjectType, GraphQLString } from 'graphql';
import express from 'express';
import { createHandler } from 'graphql-http/lib/use/express';

// Define a simple GraphQL schema for demonstration
const schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: 'Query',
    fields: {
      hello: {
        type: GraphQLString,
        resolve: () => 'world',
      },
      echo: {
        type: GraphQLString,
        args: { message: { type: GraphQLString } },
        resolve: (source, { message }) => `You said: ${message}`,
      },
    },
  }),
});

const app = express();

// Middleware to parse JSON bodies for GraphQL POST requests
app.use(express.json());

// Create an Express-specific GraphQL over HTTP handler
app.all('/graphql', createHandler({
  schema,
  // Optional: Add a context factory to pass request-specific data to resolvers
  context: (req) => ({
    userId: req.headers['x-user-id'] ?? 'guest',
    // Any other request-scoped data
  }),
}));

const port = process.env.PORT ? parseInt(process.env.PORT) : 4000;
app.listen(port, () => {
  console.log(`GraphQL server running at http://localhost:${port}/graphql`);
  console.log(`
To test, run in another terminal:
  curl -X POST -H "Content-Type: application/json" \
    --data '{"query":"query { hello }"}' \
    http://localhost:${port}/graphql
`);
  console.log(`  curl -X POST -H "Content-Type: application/json" \
    --data '{"query":"query { echo(message: \"Hello GraphQL\") }"}' \
    http://localhost:${port}/graphql
`);
});