{"id":10969,"library":"graphql-http","title":"GraphQL over HTTP Protocol Implementation","description":"graphql-http is a robust, zero-dependency JavaScript library that provides a spec-compliant implementation of GraphQL over HTTP for both server and client applications. It is currently at version 1.22.4 and receives regular updates, primarily focusing on bug fixes, performance improvements, and new platform integrations, as evidenced by its recent release cadence. The library distinguishes itself through its strict adherence to the official GraphQL over HTTP specification, offering a pluggable architecture that integrates seamlessly with various Node.js HTTP frameworks like `http`, `http2`, `Express`, `Fastify`, `Koa`, and serverless environments. It also includes an audit suite to verify compliance, making it a reliable choice for building standard-compliant GraphQL endpoints without the overhead of larger frameworks like Apollo Server, or for creating custom GraphQL clients.","status":"active","version":"1.22.4","language":"javascript","source_language":"en","source_url":"https://github.com/graphql/graphql-http","tags":["javascript","graphql","client","relay","express","apollo","server","http","transport","typescript"],"install":[{"cmd":"npm install graphql-http","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-http","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for defining and executing GraphQL schemas. It's a peer dependency, allowing users to control their GraphQL version.","package":"graphql","optional":false}],"imports":[{"note":"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.","wrong":"const { createHandler } = require('graphql-http/lib/use/express');","symbol":"createHandler","correct":"import { createHandler } from 'graphql-http/lib/use/express';"},{"note":"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.","wrong":"import { createHandler } from 'graphql-http/lib/use/http';","symbol":"createHandler","correct":"import { createHandler } from 'graphql-http';"},{"note":"The `createClient` function, used for creating a GraphQL over HTTP client, is directly exported from the root `graphql-http` package for convenience.","wrong":"import { createClient } from 'graphql-http/lib/client';","symbol":"createClient","correct":"import { createClient } from 'graphql-http';"},{"note":"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.","wrong":"import { parseRequestParams } from 'graphql-http';","symbol":"parseRequestParams","correct":"import { parseRequestParams } from 'graphql-http/lib/parse';"}],"quickstart":{"code":"import { GraphQLSchema, GraphQLObjectType, GraphQLString } from 'graphql';\nimport express from 'express';\nimport { createHandler } from 'graphql-http/lib/use/express';\n\n// Define a simple GraphQL schema for demonstration\nconst schema = new GraphQLSchema({\n  query: new GraphQLObjectType({\n    name: 'Query',\n    fields: {\n      hello: {\n        type: GraphQLString,\n        resolve: () => 'world',\n      },\n      echo: {\n        type: GraphQLString,\n        args: { message: { type: GraphQLString } },\n        resolve: (source, { message }) => `You said: ${message}`,\n      },\n    },\n  }),\n});\n\nconst app = express();\n\n// Middleware to parse JSON bodies for GraphQL POST requests\napp.use(express.json());\n\n// Create an Express-specific GraphQL over HTTP handler\napp.all('/graphql', createHandler({\n  schema,\n  // Optional: Add a context factory to pass request-specific data to resolvers\n  context: (req) => ({\n    userId: req.headers['x-user-id'] ?? 'guest',\n    // Any other request-scoped data\n  }),\n}));\n\nconst port = process.env.PORT ? parseInt(process.env.PORT) : 4000;\napp.listen(port, () => {\n  console.log(`GraphQL server running at http://localhost:${port}/graphql`);\n  console.log(`\nTo test, run in another terminal:\n  curl -X POST -H \"Content-Type: application/json\" \\\n    --data '{\"query\":\"query { hello }\"}' \\\n    http://localhost:${port}/graphql\n`);\n  console.log(`  curl -X POST -H \"Content-Type: application/json\" \\\n    --data '{\"query\":\"query { echo(message: \\\"Hello GraphQL\\\") }\"}' \\\n    http://localhost:${port}/graphql\n`);\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Internal utilities `makeResponse`, `getAcceptableMediaType`, and `isResponse` were explicitly removed from public export in v1.20.0. Code directly importing these internal helpers will break.","severity":"breaking","affected_versions":">=1.20.0"},{"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'`).","message":"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.","severity":"gotcha","affected_versions":">=1.17.1"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions using framework adapters."}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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';`.","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.","error":"ERR_REQUIRE_ESM: require() of ES Module ... not supported"},{"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`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'query')"},{"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`.","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.","error":"Error: Must provide document. | GraphQL schema is not valid."}],"ecosystem":"npm"}