GraphQL is a rising star in the domain of API development. It is gaining significant ground over REST as an API design paradigm and is becoming one of the standards for exposing the data and functionality of a web server.
In this tutorial, you’ll learn how to build an idiomatic GraphQL server entirely from scratch. You are going to use the following technologies:
The goal of this tutorial is to build an API for a Hacker News clone. Here is a quick rundown of what to expect.
You’ll start by learning how a GraphQL server works. Then you will define the GraphQL schema for your server using Nexus and write the corresponding resolver functions. In the beginning, these resolvers will only work with data that’s stored in-memory — so nothing will persist beyond the runtime of the server.
Once you have the database connected, you are going to add more advanced features to the API.
You’ll start by implementing signup/login functionality that enables users to authenticate against the API. This will also allow you to check the permissions of your users for certain API operations.
Then, you’re going to add a vote feature.
Afterwards, you’re going to learn about custom GraphQL scalars and how to add custom scalars to your application.
Then, you’ll allow the consumers of the API to constrain the list of items they retrieve from the API by adding sorting, filtering and pagination capabilities to it.
Finally you will learn how to create a automatic deployment pipeline for the API to a cloud provider (Heroku) using GitHub Actions.
Throughout the tutorial you will learn GraphQL bit by bit, through theory, writing code and reading external resources. You’ll learn not just the how of various technology choices, but also the why, including their pros, cons and tradeoffs.
This tutorial is beginner friendly. Nevertheless, some prior knowledge is necessary to follow this tutorial.
This tutorial assumes you have have
Throughout this tutorial, we’ll be making a few minor assumptions about your tools you are using:
If you’re using another set of tools, like Yarn (package manager), Windows (OS) or Webstorm (IDE), that’s totally fine and welcome! Just know that you’ll occasionally need to adapt minor instructions to your situation.
There are a few conventions and assumptions followed throughout this tutorial that you should know about. While knowing these conventions might help you follow the tutorial, it is still optional reading. Feel free to continue to the next chapter if you want to get started immediately.
Most code blocks are explained with annotations. Take the following for example. Immediately following the code block are numbered points. Each corresponds to a line annotated with that number in the code block.
const a = 1 // 1 const b: any = 1 // 2 // @ts-ignore // 3 const c: number = "Not a number";
// 1: TypeScript automatically infers the type of
numbersince it is not explicitly provided.
// 2: Use
anyto effectively disable type-checking and allow any type.
// 3: Use
// @ts-ignorebefore a line to ignore TypeScript compiler errors.
Most package installations throughout the tutorial will follow a format similar to this:
npm install package_name@^version
^ indicates to npm to keep the major version intact and update to latest minor and patch version when installing the package. According to semver rules breaking changes should only be introduced during major version upgrades. Keeping the major version fixed like this ensures there are no breaking changes in any of the packages you install that unintentionally breaks the tutorial.
If you want to upgrade a package to a new major version not instructed in the tutorial, please make sure you know what you are doing.
As you progress you’ll be writing code, of course. Often you’ll have the chance to copy and paste our code, but we strongly suggest if you’re just starting out to write the code yourself. This will expose you to the experience of writing code in a TypeScript codebase with type-safety features. This includes things like autocompletion and letting static safety guide your implementations, e.g. inside a GraphQL resolver. Also if you’re new to TypeScript getting used to encountering, understanding, and fixing static type errors is essential practice.
That said at no time should you feel frustrated. If things just aren’t working, copy-paste our work as needed. Then, once things are working, taking a moment muck around, break things, fix them again, etc. is almost always time well spent.
Note that there is a GitHub repository at https://github.com/howtographql/typescript-apollo/ containing the finished code you will build in this tutorial. You can always check this out if you get stuck during the tutorial.
Alright, let’s get started 🚀