GraphQL Helix is a collection of framework and runtime agnostic utility functions designed for building GraphQL HTTP servers. It focuses on adherence to the GraphQL over HTTP specification, enabling a single HTTP endpoint for queries, mutations, subscriptions, and features like `@defer` and `@stream` directives. The package supports both server push and client pull paradigms for real-time data. It is known for its minimal footprint, having zero dependencies outside of `graphql-js` itself, and works across Node.js, Deno, and browser environments. The current stable version is 1.13.0, with minor and patch releases occurring frequently, as indicated by recent changes adding `extensions` and `operationName` to `ExecutionContext` and improving `accept` header handling. Its key differentiators include its agnosticism to specific HTTP frameworks and runtimes, strong HTTP-first and spec-compliant approach, and a focus on providing core abstractions without bloat or integrated platforms.
npm install graphql-helixVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates setting up a basic GraphQL HTTP server using `graphql-helix` with Express, including support for queries, mutations (implied by `processRequest`), GraphiQL, and subscriptions via SSE.
Ensure your project is configured for ESM. Use `import ... from 'graphql-helix';` statements and consider setting `"type": "module"` in your `package.json`.
Install `graphql` explicitly: `npm install graphql@^15.3.0 || ^16.0.0` or `yarn add graphql@^15.3.0 || ^16.0.0`.
Client applications should be updated to correctly handle `application/graphql+json` content types if they explicitly set the `Accept` header and rely on `application/json`.
Upgrade to `graphql-helix@1.10.1` or newer to ensure proper error handling and prevent information leaks in subscription resolvers.
Ensure you are using `graphql-helix@1.9.1` or later to correctly pass and access context within your GraphQL resolvers.
Convert your consuming file to an ES Module by using `import ... from 'graphql-helix';` and ensure your `package.json` specifies `"type": "module"` or the file has a `.mjs` extension.
Ensure the `request` object you construct for `graphql-helix` contains `headers`, `method`, `query`, and `body` properties, even if some are empty objects or strings for simpler requests.
Ensure your schema is correctly built using `buildSchema` or `makeExecutableSchema` (if using `@graphql-tools`) and passed as the `schema` option to `processRequest`.
Ensure that your HTTP server implementation correctly awaits the `result.subscribe()` iterator for `MULTIPART_RESPONSE` or `PUSH` types, and properly terminates the response (e.g., `res.end()` for multipart or ensuring event stream ends).