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

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.

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, an 400 error will be returned if the query contains multiple named operations.

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.

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, graphql-express 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: request.session
})));