Teaching the MERN stack to speak GraphQL

Apollo Server is designed to work seamlessly with MERN stack (MongoDB, Express, React, Node) applications. This tutorial shows how to add Apollo Server to an existing MERN stack project. Specifically, this tutorial demonstrates how to:

• Run an Apollo Server instance that lets you execute GraphQL operations
• Expose a GraphQL route in a MERN stack application

Prerequisites

This tutorial assumes that you're familiar with the command line and JavaScript. Additionally, it requires the following:

• You've installed a recent Node.js version (v14.16.0+).
• You've completed MongoDB's MERN stack tutorial or have your own existing MERN stack application.
  • The tutorial's code examples build off the tutorial, but you can adapt them to your application's requirements.
• You have a MongoDB database with a records collection that has name, position, and level columns.
  • The tutorial's code examples use these column names, but you can adapt them to your database's schema.

Step 1: Install dependencies

In your server folder, run the following command to install these packages and save them in your server project's node_modules directory:

1
npm install graphql graphql-tag @apollo/subgraph @apollo/server

• graphql is the JavaScript reference implementation for GraphQL
• graphql-tag is a utility package to parse a GraphQL string into the standard GraphQL abstract syntax tree (AST)
• @apollo/subgraph is a utility package for creating GraphQL microservices
• @apollo/server is a spec-compliant GraphQL server that exposes a /graphql endpoint

Step 2: Define your GraphQL schema

Every GraphQL server (including Apollo Server) uses a schema to define the data that clients can query. The following example creates a schema for the prerequisite tutorial's records collection:

In your server's /src folder, create a schema.graphql file and paste in the following schema:

1
type Query {
2
  record(id:ID!): Record
3
  records: [Record]
4
}
5

6
type Mutation {
7
  createRecord(name: String!, position: String, level: String): Record
8
  deleteRecord(id: ID!): Boolean
9
  updateRecord(id: ID! name: String, position: String, level: String): Record
10
}
11

12
type Record {
13
  id: ID
14
  name: String
15
  position: String
16
  level: String
17
}

This schema lets you perform various actions on records: fetching single or multiple records, creating new records, deleting records, and updating existing records. For more information on schema definition, check out the schema basics docs.

Step 3: Define the resolvers

Resolver functions are responsible for performing the actions defined in the schema—for example, fetching and updating records. In a MERN stack application, they're how you connect the GraphQL schema to your MongoDB instance.

In your server's /src folder, create a new resolvers.js file and paste in the following resolvers:

1
import db from "./db/connection.js";
2

3
const resolvers = {
4
  Record: {
5
    id: (parent) => parent.id ?? parent._id,
6
  },
7
  Query: {
8
    async record(_, { id }) {
9
      let collection = await db.collection("records");
10
      let query = { _id: new ObjectId(id) };
11

12
      return await collection.findOne(query);
13
    },
14
    async records(_, __, context) {
15
      let collection = await db.collection("records");
16
      const records = await collection.find({}).toArray();
17
      return records;
18
    },
19
  },
20
  Mutation: {
21
    async createRecord(_, { name, position, level }, context) {
22
      let collection = await db.collection("records");
23
      const insert = await collection.insertOne({ name, position, level });
24
      if (insert.acknowledged)
25
        return { name, position, level, id: insert.insertedId };
26
      return null;
27
    },
28
    async updateRecord(_, args, context) {
29
      const id = new ObjectId(args.id);
30
      let query = { _id: new ObjectId(id) };
31
      let collection = await db.collection("records");
32
      const update = await collection.updateOne(
33
        query,
34
        { $set: { ...args } }
35
      );
36

37
      if (update.acknowledged)
38
        return await collection.findOne(query);
39

40
      return null;
41
    },
42
    async deleteRecord(_, { id }, context) {
43
      let collection = await db.collection("records");
44
      const dbDelete = await collection.deleteOne({ _id: new ObjectId(id) });
45
      return dbDelete.acknowledged && dbDelete.deletedCount == 1 ? true : false;
46
    },
47
  },
48
};
49

50
export default resolvers;

You may have noticed the code for each resolver function is similar to the code in your application's /record route. That's because these resolvers provide the same logic as performing CRUD operations on your records collection.

To learn more about writing resolver functions, check out the resolver docs.

Step 4: Add Apollo Server to your Express server

Now you can begin integrating Apollo Server into your Express server. Wherever you instantiate your express server (usually mern/server/server.js), import @apollo/server and its expressMiddleware. Then, instantiate and start the Apollo Server:

1
import express from 'express';
2
import cors from 'cors';
3
import records from "./routes/record.js";
4

5
import gql from "graphql-tag";
6
import { ApolloServer } from '@apollo/server';
7
import { buildSubgraphSchema } from '@apollo/subgraph';
8
import { expressMiddleware } from '@apollo/server/express4';
9
import resolvers from "./resolvers.js";
10
import { readFileSync } from "fs";
11

12
const PORT = process.env.PORT || 5050;
13
const app = express();
14

15
app.use(cors());
16
app.use(express.json());
17

18
const typeDefs = gql(
19
    readFileSync("schema.graphql", {
20
      encoding: "utf-8",
21
    })
22
  );
23

24
const server = new ApolloServer({
25
    schema: buildSubgraphSchema({ typeDefs, resolvers }),
26
});
27
// Note you must call `start()` on the `ApolloServer`
28
// instance before passing the instance to `expressMiddleware`
29
await server.start();
30

31
app.use("/record", records);
32

33
// start the Express server
34
app.listen(PORT, () => {
35
  console.log(`Server is running on port: ${PORT}`);
36
});

Next, you'll use the middleware to integrate the previously defined resolvers into a route.

Step 5: Add the /graphql route to your server API endpoints

In the same server file, add the /graphql route:

1
app.use("/record", records);
2
// Specify the path to mount the server
3
app.use(
4
  '/graphql',
5
  cors(),
6
  express.json(),
7
  expressMiddleware(server),
8
);
9

10
app.listen(PORT, () => {
11
  console.log(`Server is running on port: ${PORT}`);
12
});

This route provides access to the Apollo Server's resolver functions you previously defined. Note that the /records route hasn't been removed. That means your Express server can handle both GraphQL and RESTful routes.

Step 6: Start the server

You're ready to start your server! Run the following from your project's server directory:

1
npm start

Your console output should display Server is running on port: 5050.

Step 7: Execute your first query

You can now execute GraphQL queries on the server. To execute your first query, you can use Apollo Sandbox.

Visit your MERN server in your browser at the /graphql route, which will open the Apollo Sandbox:

The Sandbox UI includes:

• A URL input bar for connecting to other GraphQL servers (in the upper left)
• Tabs for schema exploration, search, and settings (on the left)
• An Operations panel for writing and executing queries (in the middle)
• A Response panel for viewing query results (on the right)

To learn more about what Sandbox offers, check out the Sandbox docs.

The server supports querying the records, so let's do it! Paste this GraphQL query string for executing the records query into the Operations panel and click the run button.

1
query GetRecords {
2
  records {
3
    name
4
    position
5
    level
6
  }
7
}

You should see your records appear in the Response panel.

Complete example

You can view and fork the complete server example on Code Sandbox:

Next steps

Congrats on completing the tutorial! 🎉 Incorporating a GraphQL server into your MERN application marks a pivotal step towards creating more efficient, flexible, and user-centric web experiences. And now that you've integrated Apollo Server into your MERN stack application, you can use GraphOS to build and scale even faster.

While this tutorial only covers the server portion of the MERN stack, the /client folder in the completed example picks up where the tutorial left off and implements @apollo/client to interact with the server. For more information on implementing the Apollo Client, head to the getting started docs.

For more hands-on learning on GraphQL and Apollo's server and client libraries, check out our interactive Odyssey tutorials.