The second of three articles focused on building Fullstack React and GraphQL with Express and Couchbase Server.

GraphQL with Express

If unfamiliar with GraphQL, take a few minutes to get up to speed using the GraphQL documentation. The following pages should be a good start:


  • node v10.x or later
  • npm v5.x or later
  • git v2.14.1 or later

Create Project Structure

We need to create a directory on your machine for our project, we will call it rage-with-couchbase:

mkdir will create a new directory using the string rage-with-couchbase for the folder’s name, bash stores that string in a variable we can use immediately named $_.

we change directories using $_ ensuring we don’t misspell the directory on the concatenated command (it’s bash magic).

Now let’s create a .gitignore file in the root of our project.

touch will generate a .gitignore file ignoring all node_modules directories and sub-directories in our project. This is important because as part of our fullstack React and GraphQL demo project, we will be tracking git changes from the root rage-with-couchbase directory, but we will have server and client directories with their own package.json and node_modules directory.

echo will add the node_modules/ text inside the .gitignore file, this will serve to ignore all node_modules directories in the root and all subdirectories.

Creating Our Express Server

Now we will create the directory to store our Express server and we will use npm to manage its packages.

mkdir will create a new folder inside the project root specifically for our server using the string couchbase-gql-server for the name, this is your server project directory.

we change directories and use the $_ (more magic) and then we initialize an npm project using npm init -y accepting the default values with the -y flag.

Install Express Server Dependencies

Once install is finished, we need to open our project with our editor of choice. I prefer VS Code.

Create Our GraphQL Server

Require express/express-graphql/graphql in our server.js file:

The first three imports are needed for our GraphQL server and the last import is required for connecting to and querying our Couchbase Server.

Initialize Express and Connect to Our Bucket

Add the following code:

Above we are connecting to our Couchbase Server cluster, authenticating with our user that we set up, and opening our travel-sample bucket. Never use default usernames and passwords in production applications.

Create Our GraphQL Schema

Adding the code below will define two endpoints that will enable our GraphQL Server to access and retrieve data from our documents inside of our Couchbase Server bucket.

The Query type specifies which GraphQL queries clients can execute against its own data graph.

We have two endpoints defined by that Query. One named “airlinesUK” and the other “airlineByKey”. In our React app, we will only use the “airlinesUK” endpoint. I made the “airlineByKey” endpoint simply to show an example of retrieving a single Couchbase document by key. This operation does not use the N1QL query language and therefore does not have any additional overhead. Understanding when and where to use each is important from the perspective of building the API, we wouldn’t want to use a N1QL query to return a single document that we can get by key.

In our GraphQL code, we have an object of type Airline. This object model the document structure found in our Couchbase travel-sample bucket where the type is “airline”.

Next, we have an Endpoint named “airlinesUK“. Notice that the return value of this endpoint is an array of Airline: [Airline]. This means we will be getting a list of airlines back.

We also have “airlineByKey” endpoint where we will fetch a single Airline.

If you remember from our Bucket images above, each document is defined by a key in a format like airline_1234 where 1234 is the id of the airline.

travel-sample document

We will keep this id in mind when using the NodeJS SDK to fetch our individual airlineByKey using a simple bucket.get() method.

Create Our Resolver Implementation for Each Endpoint

Now, that we have defined two queries in our GraphQL-Express API using our schema object, we need implementation in JavaScript for retrieving the data.

Our React application that we will create will only need the N1QL query named airlinesUK.

But I wanted to show you how to query without N1QL using the NodeJS SDK’s API using just a key or extending it to use a region (US/UK, etc..), that is the airlineByKey and airlineByRegion implementation.

Add the following code to our server.js file for our N1QL queries:
(In your JS code, ensure to escape backticks with backslashes)

Add the following code to our server.js file for our GraphQL resolvers:

Note: In the N1QL statement above, you will need to escape the backticks in the FROM line around travel-sample with backslashes. Our blog’s code sample does not show those Backslashes, but they are there and they are in the Final Source Code

Just to drive this home, we are using two different methods to query our Couchbase Server.

The first method corresponds to the airlinesUK endpoint, this is its resolver. We need to return a promise and inside rely on bucket.queryto take a predefined N1QL query that I have broken up line by line in the statement variable for readability. Being able to run this type of SQL query is very powerful for a document database. A lot of the SQL we know transfers over and this is a big relief compared to other document databases that have a brand new API and query language you will need to learn.

The second method corresponds to the airlinesUK endpoint, this is its resolver. We need to return a promise and inside rely on bucket.get method and in this case, we are just defining the key of our document. Remember that one of the great things about using a key-value data store is that we can easily pick out a single document with little overhead.

Each of the methods above also tests for query errors and either resolve or reject based on a result or error.

Creating Our GraphQL with Express Server

Now that we have everything sorted out for our endpoints and queries, all we need to do is use our Express server and give it a port to run on, let’s do that now.

Add the following code to the end of our server.js file:

If you have ever created an Express or Express-GraphQL server, this code should look familiar.

First, we set up our port and GraphQL URL.

Next, we pass in our GraphQL schema and its resolvers and set our graphiql option to true. (This will give us an IDE to test our GraphQL queries available at localhost:4000/graphql.

Finally, we listen on port 4000 and set a message in the console to indicate our server is running.

Let’s run our server, ensure that your Couchbase:

Once we have the GraphQL server running we can test the AirlinesUK query by pasting the following code into the GraphQL IDE query pane:

As the query indicates it will retrieve all of our UK based airlines:

GraphQL with Express GraphiQL demo all UK airlines

Next, we will use the airlineByKey endpoint, in this example, we will also need to create a query variable and paste it into the respective pane:

And with that in place and we can query again and retrieve a single airline document by key:

GraphQL with Express GraphiQL demo UK airline by key

With a super simple GraphQL API setup, we are ready to create our react application that will use these endpoints for a master-detail page using the UK airlines in a list component and when we click a particular Airline, another component will show the full details of the airline on the right side of the page.

Create Apollo GraphQL Client in React (Part 3)


Posted by Eric Bishard

International speaker, blogging and advocating for the JavaScript, React, GraphQL and NoSQL community working as a Senior Developer Advocate for Couchbase.

Leave a reply