Creating A GraphQL Server With Node.js And Express

This post has been published first on

GraphQL is a language that enables you to provide a complete and understandable description of the data in your API. Furthermore it gives clients the power to ask for exactly what they need and nothing more. The project’s website can be found at

There are several advantages of GraphQL.

GraphQL is declarative: Query responses are decided by the client rather than the server. A GraphQL query returns exactly what a client asks for and no more.

GraphQL is compositional: A GraphQL query itself is a hierarchical set of fields. The query is shaped just like the data it returns. It is a natural way for product engineers to describe data requirements.

GraphQL is strongly-typed: A GraphQL query can be ensured to be valid within a GraphQL type system at development time allowing the server to make guarantees about the response. This makes it easier to build high-quality client tools

In this tutorial you’ll learn how to setup a GraphQL server with Node.js and Express. We’ll be using the Express middleware express-graphql in our example. Furthermore you’ll learn how to use GraphQL on the client side to send queries and mutations to the server.

Let’s get started …

Setting Up The Project

To setup a GraphQL Node.js server let’s start with creating a new empty project folder first:

Change into that directory and initiate a new package.json file by executing the following NPM command:

Furthermore create a new server.js file in the project directory. That will be the file where the code required to implement the Node.js GraphQL server will be inserted in the next section:

Finally make sure that NPM packages graphql, express and express-graphql are added to the project:

Having installed these packages successfully we’re now ready to implement a first GraphQL server.

Creating A Basic GraphQL Server With Express

Now that the Project setup is ready let’s create the a first server implementation by inserting the following JS code in server.js:

At first we’re making sure that express, express-graphql and the buildSchema function from the graphql package are imported. Next we’re creating a simple GraphQL schema by using the buildSchema function.

To create the schema we’re calling the function and passing in a string that contains the IDL (GraphQL Interface Definition Language) code which is used to describe the schema. A GraphQL schema is used to describe the complete APIs type system. It includes the complete set of data and defines how a client can access that data. Each time the client makes an API call, the call is validated against the schema. Only if the validation is successful the action is executed. Otherwise an error is returned.

Next a root resolver is created. A resolver contains the mapping of actions to functions. In our example from above the root resolver contains only one action: message. To keep things easy the assigned functions just returns the string Hello World!. Later on you’ll learn how to include multiple actions and assign different resolver functions.

Finally the Express server is created with a GraphQL endpoint: /graphql. To create the GraphQL endpoint first a new express instance is stored in app. Next the app.use method is called and two parameters are provided:

  • First the URL endpoint as string
  • Second the result of the express_graphql function is handed over. A configuration object is passed into the call of express_graphql containing three properties

The three configuration properties which are used for the Express GraphQL middleware are the following:

  • schema: The GraphQL schema which should be attached to the specific endpoint
  • rootValue: The root resolver object
  • graphiql: Must be set to true to enable the GraphiQL tool when accessing the endpoint in the browser. GraphiQL is a graphical interactive in-browser GraphQL IDE. By using this tool you can directly write your queries in the browser and try out the endpoint.

Finally app.listen is called to start the server process on port 4000.

The Node.js server can be started by executing the following command in the project directory:

Having started the server process you should be able to see the output

Express GraphQL Server Now Running On localhost:4000/graphql

on the command line. If you access localhost:4000/graphql in the browser you should be able to see the following result:

In the query editor type in the following code:

Next hit the Execute Query button and you should be able to see the following result:

Implementing A More Sophisticated Example

Now that you have a basic understanding of how to implement a GraphQL server with Node.js and Express, let’s continue with a more sophisticated example. Add a new JS file to the project:

Next let’s add the following implementation:

Ok, let’s examine the code step by step. First we’re defining a schema which now consists of a custom type Course and two query actions.

The Course object type consist of six properties in total. The defined query actions enable the user to retrieve a single course by ID or retrieving an array of Course objects by course topic.

To be able to return data without the need to connect to a database we’re defining the coursesData array with some dummy course data inside.

In the root resolver we’re connecting the course query action to the getCourse function and the courses query action to the getCourses function.

Accessing The GraphQL API

Now let’s start the Node.js server process again and execute the code from file server2.js with the following command:

If you’re opening up URL localhost:4000/graphql in the browser you should be able to see the GraphiQL web interface, so that you can start typing in queries. First let’s retrieve one single course from our GraphQL endpoint. Insert the following query code:

The getSingleCourse query operation is expecting to get one parameter: $courseID of type Int. By usign the exclamation mark we’re specifying that this parameters needs to be provided.

Within the getSingleCourse we’re executing the course query and for this specific ID. We’re specifying that we’d like to retrieve title, author, description, topic and url of that that specific course.

Because the getSingleCourse query operation uses a dynamic parameter we need to supply the value of this parameter in the Query Variables input field as well:

Click on the execute button and you should be able to see the following result:

Using Aliases & Fragments

You’re able to include multiple queries in one query operation. In the following example the getCourseWithFragments query operations contains two queries for single courses. To distinguish between both queries we’re assigning aliases: course1 and course2.

As you can see the query operations requires two parameters: courseID1 and courseID2. The first ID is used for the first query and the second ID is used for the second query.

Another feature which is used is a fragment. By using a fragment we’re able to avoid repeating the same set of fields in multiple queries. Instead we’re defining a reusable fragment with name courseFields and specific which fields are relevent for both queries in one place.

Before executing the query operation we need to assign values to the parameters:

The result should look like the following:

Creating And Using Mutations

So far we’ve only seen examples which fetches data from our GraphQL server. With GraphQL we’re also able to modify data. by using Mutations. To be able to use a mutation with out GraphQL server we first need to add code to our server implementation in server2.js:

Here you can see the schema is now containing a Mutation type as well. The mutation which is defined is named updateCourseTopic and takes two mandatory parameter: id and topic. The return type of that mutation is Course.

Using that mutation it should be possible to change the topic of a specific course. In the same way like we did it before for queries we’re now assigning a function to the mutation in the root resolver. The function is implemented with the corresponding update logic:

Now the sever is able to handle mutations as well, so let’s try it out in the GraphiQL browser interface again.

A mutation operation is defined by using the mutation keyword followed by the name of the mutation operation. In the following example the updateCourseTopic mutation is included in the operation and again we’re making use of the courseFields fragment.

The mutation operation is using two dynamic variables so we need to assign the values in the query variables input field as follows:

By executing this mutation we’re changing the value of the topic property for the course data set with ID 1 from Node.js to JavaScript. As a result we’re getting back the changed course:


GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more.

In this tutorial you’ve learned how to implement your own GraphQL server with Node.js and Express. By using the Express middleware express-graphql setting up a GraphQL server is really easy and is requiring only few lines of code. If you’d like to to dive deeper into the GraphQL language also check out

This post has been published first on

Top Online Course Recommendations

#1 GraphQL with React: The Complete Developers Guide

Learn and master GraphQL by building real web apps with React and Node
Go To Course …

#2 The Complete Web Developer in 2018

Learn to code and become a web developer in 2018 with HTML5, CSS, Javascript, React, Node.js, Machine Learning & more!
Go To Course …

#3 The Complete JavaScript Course — Build a Real-World Project

Master JavaScript with the most complete JavaScript course on the market! Includes projects, challenges, final exam, ES6
Go To Course …

Disclaimer: This post contains affiliate links, which means that if you click on one of the product links, I’ll receive a small commission. This helps support this blog! Blog

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store