Express GraphQL Request Body Parser

1.1.0 verified Thu Apr 23 auth: no javascript abandoned

body-parser-graphql is an Express.js middleware designed to process incoming HTTP requests with the `Content-Type` header set to `application/graphql`. Upon receipt, it transparently transforms the raw GraphQL query string from the request body into a standard `application/json` format, typically an object with a `query` property containing the GraphQL operation. This allows existing GraphQL server implementations, which usually expect `application/json` payloads, to seamlessly consume queries sent with the `application/graphql` Content-Type. The current stable version is 1.1.0, released in April 2018. However, the package has been archived and is no longer actively maintained as of March 2023, meaning users should consider alternatives or built-in solutions provided by modern GraphQL server libraries.

Common errors

error TypeError: app.use() requires a middleware function but got a undefined ↓

cause The `bodyParserGraphQL` function was imported but not called, or the named export was incorrectly accessed.

fix

Ensure the middleware is called: app.use(bodyParserGraphQL()) or app.use(bodyParser.graphql()).

error POST body missing. Did you forget use body-parser middleware? ↓

cause This error usually indicates that `req.body` is empty because the `Content-Type` header was incorrect, or the middleware was not applied, or an upstream middleware consumed the body prematurely.

fix

Verify the client is sending Content-Type: application/graphql and the GraphQL query string directly in the body. Ensure app.use(bodyParserGraphQL()) is called early in your middleware stack.

error Error: request entity too large ↓

cause The incoming request body size exceeded the default limit configured for the underlying `body-parser` instance (typically 100kb).

fix

Pass options to increase the limit, e.g., app.use(bodyParserGraphQL({ limit: '5mb' })).

Warnings

breaking The `body-parser-graphql` package is no longer actively maintained. Its GitHub repository was archived on March 20, 2023, and is now read-only. This means there will be no further updates, bug fixes, or security patches. ↓

fix Migrate to alternatives, such as `express-graphql` which includes its own body parsing capabilities, or handle `application/graphql` content-type manually in custom middleware.

gotcha This package internally relies on `body-parser` functionality. While `body-parser` itself is actively maintained, this wrapper may use an older, fixed version of `body-parser` or have compatibility issues with newer versions of Express.js or Node.js without updates. ↓

fix Carefully test compatibility with your specific Express.js and Node.js versions. For long-term projects, consider alternatives that are actively maintained and integrated with modern frameworks.

gotcha The middleware expects a raw GraphQL query string in the request body when `Content-Type` is `application/graphql`. If the client sends a JSON object (e.g., `{ query: "..." }`) with `Content-Type: application/graphql`, it might not be parsed as expected, or could lead to errors. It converts `application/graphql` to `application/json` with the query string as the value of the `query` property. ↓

fix Ensure clients send the raw GraphQL query string as the body with `Content-Type: application/graphql`. If clients send JSON, use standard `express.json()` middleware and ensure the `Content-Type` is `application/json`.

Install

npm install body-parser-graphql

yarn add body-parser-graphql

pnpm add body-parser-graphql

Imports

bodyParserGraphQL

wrong

import bodyParserGraphQL from 'body-parser-graphql'

correct

import { bodyParserGraphQL } from 'body-parser-graphql'

The primary middleware function is a named export.

* as bodyParser
wrong
```
const bodyParser = require('body-parser-graphql')
```
correct
```
import * as bodyParser from 'body-parser-graphql'
```
Imports all exports as a namespace. This is typically used to then access `bodyParser.graphql()`.
CommonJS require
wrong
```
const bodyParserGraphQL = require('body-parser-graphql').default
```
correct
```
const { bodyParserGraphQL } = require('body-parser-graphql')
```
While TypeScript definitions exist, the package behavior aligns with named CommonJS exports for the main function.

Quickstart

Demonstrates setting up `body-parser-graphql` middleware in an Express application to handle `application/graphql` requests and access the parsed query on `req.body`.

import * as express from 'express';
import { bodyParserGraphQL } from 'body-parser-graphql';

const app = express();

// Integrate the GraphQL body parser middleware
app.use(bodyParserGraphQL());

// Example GraphQL endpoint (assuming a GraphQL server handler)
app.post('/graphql', (req, res) => {
  // req.body will now contain the parsed GraphQL query as a JSON object
  // e.g., { query: "{ posts { id title } }" }
  console.log('Received GraphQL query:', req.body.query);
  res.json({
    data: {
      message: 'Hello from GraphQL endpoint!',
      receivedQuery: req.body.query
    }
  });
});

const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`);
  console.log('Try sending a POST request to /graphql with Content-Type: application/graphql');
  console.log('Body: { posts { id title } }');
});