Installing Apollo Server: Your GraphQL API Foundation

Previously in this course, we discussed Initializing a Node.js Project: Setup for GraphQL Servers. Now that you have a clean package.json file and a structured project directory, it is time to transform that empty folder into a fully-fledged GraphQL API server.

To build a modern GraphQL API in Node.js, we rely on the industry-standard library: Apollo Server. It abstracts away the complex HTTP plumbing, allowing you to focus on your data and business logic.

Why Apollo Server?

While you can run GraphQL using the reference implementation (graphql-js), doing so requires writing a significant amount of boilerplate code to handle HTTP requests, parsing bodies, and managing the request lifecycle.

Apollo Server acts as the "glue." It provides the middleware necessary to interpret incoming requests, execute your schema against your resolvers, and format the response according to the GraphQL specification. It is the engine that powers the client-server relationship we discussed earlier.

Installing Dependencies

Before we can define our schema or write resolvers, we need two core packages:

1. @apollo/server: The core library for the Apollo Server instance.
2. graphql: The reference implementation of GraphQL that Apollo uses under the hood.

Open your terminal in the root directory of your project and run:

Bash
npm install @apollo/server graphql

If you are unfamiliar with how npm handles your package.json file during this process, I highly recommend reviewing our guide on Managing Dependencies: npm install and package.json Explained.

Verifying the Installation

To verify that the installation was successful, we will perform a "smoke test." This involves creating a simple entry file—usually index.js or server.js—and importing the main constructor from the Apollo package.

Create a file named src/index.js and add the following code:

JAVASCRIPT
const { ApolloServer } = require(CE9178">'@apollo/server');

// A simple check to ensure the import works
if (ApolloServer) {
  console.log(CE9178">'Apollo Server successfully imported!');
} else {
  console.error(CE9178">'Failed to load Apollo Server.');
}

Now, execute this file using Node:

Bash
node src/index.js

If your terminal outputs "Apollo Server successfully imported!", your development environment is correctly configured. You are now ready to begin building your typed schema.

Common Pitfalls

Even with a simple installation, developers often encounter a few recurring issues:

• Version Mismatches: Apollo Server 4+ requires a specific version of graphql. Always ensure you are using the latest stable versions to avoid peer dependency conflicts.
• CommonJS vs. ESM: Depending on your package.json configuration ("type": "module"), you might need to use import instead of require. If you encounter errors, check your project's module system.
• Node.js Version: Apollo Server relies on modern JavaScript features. Ensure you are running Node.js version 18 or higher to avoid syntax errors related to older environment limitations.

Hands-on Exercise

To cement your progress, perform these three steps:

1. Check your package.json to confirm that @apollo/server and graphql appear under the dependencies object.
2. If you haven't already, ensure your project is using a .gitignore file to ignore the node_modules directory.
3. Update your package.json to include a start script: "start": "node src/index.js". Run npm start to verify that your script is correctly linked to your entry file.

FAQ

Do I need to install express as well? Not necessarily. Apollo Server 4 includes a built-in standalone server. You only need to add express if you intend to add custom middleware or integrate with an existing Express application.

Is graphql a dependency of Apollo? Yes, but it is best practice to install it explicitly so you have control over the specific version of the GraphQL engine being used in your project.

Does this setup include a database? No. At this stage, we are only setting up the runtime environment. We will handle data fetching and persistent storage in later lessons.

Recap

In this lesson, we transitioned from an empty Node.js project to a functional GraphQL environment. By installing @apollo/server and graphql, you have laid the foundation for the API we will build throughout this course. You verified the installation, configured your entry script, and ensured your dependency tree is clean.

Up next: Defining the TypeDefs — we will write your first GraphQL schema and export it to the server.