express-graphql

What is express-graphql?

The express-graphql package is a middleware for integrating GraphQL with an Express server. It allows you to create a GraphQL HTTP server with Express, enabling you to define a schema, resolve functions, and handle GraphQL queries and mutations.

What are express-graphql's main functionalities?

Setting up a basic GraphQL server

This code sets up a basic GraphQL server using express-graphql. It defines a simple schema with a single query 'hello' and a root resolver that returns 'Hello world!'. The server listens on port 4000 and provides a GraphiQL interface for testing queries.

const express = require('express');
const { graphqlHTTP } = require('express-graphql');
const { buildSchema } = require('graphql');

const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

const root = { hello: () => 'Hello world!' };

const app = express();
app.use('/graphql', graphqlHTTP({
  schema: schema,
  rootValue: root,
  graphiql: true,
}));

app.listen(4000, () => console.log('Now browse to localhost:4000/graphql'));

Enabling GraphiQL interface

This code demonstrates how to enable the GraphiQL interface, an in-browser IDE for exploring GraphQL. By setting the 'graphiql' option to true, you can navigate to '/graphql' in your browser and interact with your GraphQL API.

const express = require('express');
const { graphqlHTTP } = require('express-graphql');
const { buildSchema } = require('graphql');

const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

const root = { hello: () => 'Hello world!' };

const app = express();
app.use('/graphql', graphqlHTTP({
  schema: schema,
  rootValue: root,
  graphiql: true,
}));

app.listen(4000, () => console.log('Now browse to localhost:4000/graphql'));

Handling mutations

This code shows how to handle mutations in a GraphQL server. It defines a schema with a 'setMessage' mutation and a 'getMessage' query. The 'setMessage' mutation updates a message variable, and the 'getMessage' query retrieves the current message.

const express = require('express');
const { graphqlHTTP } = require('express-graphql');
const { buildSchema } = require('graphql');

const schema = buildSchema(`
  type Mutation {
    setMessage(message: String): String
  }
  type Query {
    getMessage: String
  }
`);

let message = 'Hello world!';

const root = {
  setMessage: ({ message: newMessage }) => {
    message = newMessage;
    return message;
  },
  getMessage: () => message,
};

const app = express();
app.use('/graphql', graphqlHTTP({
  schema: schema,
  rootValue: root,
  graphiql: true,
}));

app.listen(4000, () => console.log('Now browse to localhost:4000/graphql'));

Other packages similar to express-graphql

apollo-server-express

Apollo Server is a community-maintained open-source GraphQL server that works with various Node.js HTTP server frameworks, including Express. It provides a more feature-rich and flexible solution compared to express-graphql, with built-in support for schema stitching, subscriptions, and more.

graphql-yoga

GraphQL Yoga is a fully-featured GraphQL server with focus on easy setup, performance, and great developer experience. It is built on top of Apollo Server and Express, offering additional features like out-of-the-box support for GraphQL subscriptions and file uploads.

README

GraphQL Express Middleware

Create a GraphQL HTTP server with Express.

npm install --save express-graphql

Install express-graphql as middleware in your express server:

var graphqlHTTP = require('express-graphql');

var app = express();

app.use('/graphql', graphqlHTTP({ schema: MyGraphQLSchema, graphiql: true }));

Options

The graphqlHTTP function accepts the following options:

• schema: A GraphQLSchema instance from graphql-js. A schema must be provided.

• rootValue: A value to pass as the rootValue to the graphql() function from graphql-js.

• pretty: If true, any JSON response will be pretty-printed.

• formatError: An optional function which will be used to format any errors produced by fulfilling a GraphQL operation. If no function is provided, GraphQL's default spec-compliant formatError function will be used.

• validationRules: Optional additional validation rules queries must satisfy in addition to those defined by the GraphQL spec.

• graphiql: If true, may present GraphiQL when loaded directly from a browser (a useful tool for debugging and exploration).

Debugging

During development, it's useful to get more information from errors, such as stack traces. Providing a function to formatError enables this:

formatError: error => ({
  message: error.message,
  locations: error.locations,
  stack: error.stack
})

HTTP Usage

Once installed at a path, express-graphql will accept requests with the parameters:

• query: A string GraphQL document to be executed.

• variables: The runtime values to use for any GraphQL query variables as a JSON object.

• operationName: If the provided query contains multiple named operations, this specifies which operation should be executed. If not provided, a 400 error will be returned if the query contains multiple named operations.

• raw: If the graphiql option is enabled and the raw parameter is provided raw JSON will always be returned instead of GraphiQL even when loaded from a browser.

GraphQL will first look for each parameter in the URL's query-string:

/graphql?query=query+getUser($id:ID){user(id:$id){name}}&variables={"id":"4"}

If not found in the query-string, it will look in the POST request body.

If a previous middleware has already parsed the POST body, the request.body value will be used. Use multer or a similar middleware to add support for multipart/form-data content, which may be useful for GraphQL mutations involving uploading files. See an example using multer.

If the POST body has not yet been parsed, graphql-express will interpret it depending on the provided Content-Type header.

• application/json: the POST body will be parsed as a JSON object of parameters.

• application/x-www-form-urlencoded: this POST body will be parsed as a url-encoded string of key-value pairs.

• application/graphql: The POST body will be parsed as GraphQL query string, which provides the query parameter.

Advanced Options

In order to support advanced scenarios such as installing a GraphQL server on a dynamic endpoint or accessing the current authentication information, express-graphql allows options to be provided as a function of each express request.

This example uses express-session to run GraphQL on a rootValue based on the currently logged-in session.

var session = require('express-session');
var graphqlHTTP = require('express-graphql');

var app = express();

app.use(session({ secret: 'keyboard cat', cookie: { maxAge: 60000 }}));

app.use('/graphql', graphqlHTTP(request => ({
  schema: MySessionAwareGraphQLSchema,
  rootValue: { session: request.session },
  graphiql: true
})));

Then in your type definitions, access session from the rootValue:

new GraphQLObjectType({
  name: 'MyType',
  fields: {
    myField: {
      type: GraphQLString,
      resolve(parentValue, _, { rootValue: { session } }) {
        // use `session` here
      }
    }
  }
});