Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createHandler
✓ import { createHandler } from 'graphql-http/lib/use/express';
✗ const { createHandler } = require('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
✓ import { createHandler } from 'graphql-http';
✗ import { createHandler } from 'graphql-http/lib/use/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
✓ import { createClient } from 'graphql-http';
✗ import { createClient } from 'graphql-http/lib/client';
The `createClient` function, used for creating a GraphQL over HTTP client, is directly exported from the root `graphql-http` package for convenience.
parseRequestParams
✓ import { parseRequestParams } from 'graphql-http/lib/parse';
✗ import { parseRequestParams } from 'graphql-http';
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.
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
`);
});
Debug
Known issues
breakingInternal utilities `makeResponse`, `getAcceptableMediaType`, and `isResponse` were explicitly removed from public export in v1.20.0. Code directly importing these internal helpers will break.fixAvoid 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.
affects: >=1.20.0
gotchaAs 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.fixEnsure 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'`). affects: >=1.17.1
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.fixInstall 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.
affects: >=0.1.0
gotchaWhen 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.fixFor 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).
affects: All versions using framework adapters.
Errors
Common errors & fixes
ERR_REQUIRE_ESM: require() of ES Module ... not supported
Attempting to use `require()` to import `graphql-http` or its adapter modules in a CommonJS context, while `graphql-http` is primarily an ESM package.
fixEnsure 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')
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.
fixAdd 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.
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.
fixVerify 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`.
Audit
Dependencies
graphqlrequiredRequired for defining and executing GraphQL schemas. It's a peer dependency, allowing users to control their GraphQL version.