Registry / http-networking / graphql-helix

graphql-helix

JSON →
library1.13.0jsnpmunverified

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-helix
INSTALL
IMPORT
SIG · GRAPHQL-HELIX
G
graphql-helix
http-networkingjavascriptv1.13.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

processRequest
import { processRequest } from 'graphql-helix';
const { processRequest } = require('graphql-helix');
The library primarily uses ESM imports; CommonJS `require` might lead to issues in modern setups or be incompatible.
getGraphQLParameters
import { getGraphQLParameters } from 'graphql-helix';
import getGraphQLParameters from 'graphql-helix';
This is a named export, not a default export.
renderGraphiQL
import { renderGraphiQL } from 'graphql-helix';
import * as helix from 'graphql-helix'; helix.renderGraphiQL();
Use direct named imports for clarity and tree-shaking benefits.

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.

import express from 'express'; import { buildSchema } from 'graphql'; import { getGraphQLParameters, processRequest, renderGraphiQL, shouldRenderGraphiQL, } from 'graphql-helix'; const schema = buildSchema(` type Query { hello: String } type Subscription { greeting: String } `); const rootValue = { hello: () => 'Hello GraphQL Helix!', greeting: async function* () { for (const hi of ['Hi', 'Bonjour', 'Hola', 'Ciao']) { yield { greeting: hi }; await new Promise(resolve => setTimeout(resolve, 500)); } }, }; const app = express(); app.use(express.json()); app.use('/graphql', async (req, res) => { const request = { body: req.body, headers: req.headers, method: req.method, query: req.query, }; if (shouldRenderGraphiQL(request)) { res.send(renderGraphiQL()); } else { const { operationName, query, variables } = getGraphQLParameters(request); const result = await processRequest({ operationName, query, variables, request, schema, contextFactory: () => ({ request }), rootValue, }); if (result.type === 'RESPONSE') { result.headers.forEach(({ name, value }) => res.setHeader(name, value)); res.status(result.status); res.json(result.payload); } else if (result.type === 'MULTIPART_RESPONSE') { res.writeHead(200, { Connection: 'keep-alive', 'Content-Type': 'multipart/mixed; boundary="-"', 'Transfer-Encoding': 'chunked', }); req.on('close', () => { result.unsubscribe(); }); res.write('---'); for await (const chunk of result.subscribe()) { res.write(`\r\n${JSON.stringify(chunk)}\r\n---`); } res.end(); } else if (result.type === 'PUSH') { res.writeHead(200, { 'Content-Type': 'text/event-stream', Connection: 'keep-alive', 'Cache-Control': 'no-cache', }); req.on('close', () => { result.unsubscribe(); }); for await (const event of result.subscribe()) { res.write(`data: ${JSON.stringify(event)}\n\n`); } } } }); app.listen(4000, () => console.log('GraphQL server running on http://localhost:4000/graphql'));
Debug
Known issues
breakingGraphQL Helix moved to supporting only ESM (ECMAScript Modules) in its newer versions. While `require` might work in some transpiled environments, native ESM imports (`import`) are the intended and fully supported way to consume the library.
fix
Ensure your project is configured for ESM. Use `import ... from 'graphql-helix';` statements and consider setting `"type": "module"` in your `package.json`.
affects: >=1.0.0
gotchaThe `graphql` package is a peer dependency. Installing `graphql-helix` without a compatible version of `graphql` will lead to runtime errors or module resolution issues.
fix
Install `graphql` explicitly: `npm install graphql@^15.3.0 || ^16.0.0` or `yarn add graphql@^15.3.0 || ^16.0.0`.
affects: >=1.0.0
gotchaSince `graphql-helix@1.11.0`, clients accepting `application/graphql+json` (via the `Accept` header) will receive responses with `Content-Type: application/graphql+json` instead of `application/json` for spec compliance. Clients not specifying an `Accept` header still receive `application/json`.
fix
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`.
affects: >=1.11.0
gotchaPrior to `graphql-helix@1.10.1`, errors thrown within `subscribe` handlers for `Subscription` root types were not properly handled and could expose internal error messages to clients.
fix
Upgrade to `graphql-helix@1.10.1` or newer to ensure proper error handling and prevent information leaks in subscription resolvers.
affects: <1.10.1
gotchaIssues with context passing in `processRequest` (specifically related to `contextValue`) were patched in `graphql-helix@1.9.1`, potentially leading to `undefined` or incorrect context in resolvers for earlier versions.
fix
Ensure you are using `graphql-helix@1.9.1` or later to correctly pass and access context within your GraphQL resolvers.
affects: <1.9.1
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/graphql-helix/lib/index.js from .../server.js not supported.
Attempting to use `require()` to import `graphql-helix` in a CommonJS module, but `graphql-helix` is an ES Module.
fix
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.
TypeError: Cannot read properties of undefined (reading 'headers') at getGraphQLParameters
The `request` object passed to `getGraphQLParameters` or `processRequest` is missing the `headers` property or is `undefined`.
fix
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.
Error: GraphQL.js cannot execute a request, because the provided schema is not a valid GraphQLSchema instance.
`processRequest` received an invalid `schema` object; it must be a valid `GraphQLSchema` instance from `graphql-js`.
fix
Ensure your schema is correctly built using `buildSchema` or `makeExecutableSchema` (if using `@graphql-tools`) and passed as the `schema` option to `processRequest`.
RangeError: Maximum call stack size exceeded (on multipart/mixed responses or SSE)
Improper handling of asynchronous iterators for `@defer`/`@stream` or subscriptions, or not closing the HTTP connection properly after sending all parts.
fix
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).
Upgrade
Version history
1.13.0latest on npm
Audit
Dependencies
graphqlrequiredPeer dependency required for GraphQL schema and execution logic.
Agent activity
4 hits · last 30 days
node
4
Resources
graphql-helix — npm install graphql-helix · libregistry