GraphQL Helix HTTP Server Utilities

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/graphql-helix/lib/index.js from .../server.js not supported.

  cause 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

  cause 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.

  cause `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)

  cause 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).

Warnings

• breaking GraphQL 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`.
• gotcha The `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`.
• gotcha Since `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`.
• gotcha Prior 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.
• gotcha Issues 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.

Install

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

Imports

• processRequest
  wrong:

  const { processRequest } = require('graphql-helix');

  correct:

  import { processRequest } from 'graphql-helix';

  The library primarily uses ESM imports; CommonJS `require` might lead to issues in modern setups or be incompatible.
• getGraphQLParameters
  wrong:

  import getGraphQLParameters from 'graphql-helix';

  correct:

  import { getGraphQLParameters } from 'graphql-helix';

  This is a named export, not a default export.
• renderGraphiQL
  wrong:

  import * as helix from 'graphql-helix'; helix.renderGraphiQL();

  correct:

  import { renderGraphiQL } from 'graphql-helix';

  Use direct named imports for clarity and tree-shaking benefits.

Quickstart

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'));