1. Setup and first query

Overview

In this first chapter we're just going to get the bare minimum of a Nexus project setup. You'll learn about:

• The nexus package
• The ts-node-dev package to run your app
• Laying out and running a Nexus project
• GraphQL Playground

CLI

Start by creating your project directory, initializing your package.json, and adding the needed runtime dependencies.

$mkdir nexus-tutorial && cd nexus-tutorial
$npm init -y
$npm install nexus graphql apollo-server

Note: nexus works with any GraphQL compliant server. We'll use apollo-server in this tutorial, but you're free to use whichever fits your use-case best.

We'll also need typescript and ts-node-dev as dev dependencies. ts-node-dev will enable you to transpile your TS files on the fly and restart your API on changes.

$npm install --save-dev typescript ts-node-dev

To properly get full advantage of TypeScript, we'll need a tsconfig.json file. Create one at the root of your project and copy paste the following

1{
2  "compilerOptions": {
3    "target": "ES2018",
4    "module": "commonjs",
5    "lib": ["esnext"],
6    "strict": true,
7    "rootDir": ".",
8    "outDir": "dist",
9    "sourceMap": true,
10    "esModuleInterop": true
11  }
12}

Let's finally add some npm scripts to simplify our future workflows

1"scripts": {
2  "test": "echo \"Error: no test specified\" && exit 1",
+  "dev": "ts-node-dev --transpile-only --no-notify api/index.ts",
+  "build": "tsc"
5}

Creating our app layout

We'll now create our first module at api/schema.ts:

$mkdir api && touch api/schema.ts

We'll then setup nexus to create an empty schema

1// api/schema.ts
2import { makeSchema } from 'nexus'
3import { join } from 'path'
4
5export const schema = makeSchema({
6  types: [], // 1
7  outputs: {
8    typegen: join(__dirname, '..', 'nexus-typegen.ts'), // 2
9    schema: join(__dirname, '..', 'schema.graphql'), // 3
10  },
11})

1. GraphQL types that will be used to construct your GraphQL schema. It's voluntarily empty for now.
2. Output path to where nexus should write the generated TypeScript definition types derived from your schema. This is mandatory to benefit from Nexus' type-safety. We call this system "reflection". More on it later.
3. Output path to where nexus should write the SDL version of your GraphQL schema. More on it later as well.

Finally, we'll setup the GraphQL server. We'll intentionally separate the server instantiation from the server listening to make testing easier later.

Create api/server.ts and api/index.ts files and add the following code to instantiate your GraphQL server:

1// api/server.ts
2import { ApolloServer } from 'apollo-server'
3import { schema } from './schema'
4
5export const server = new ApolloServer({ schema })

1// api/index.ts
2import { server } from './server'
3
4server.listen().then(({ url }) => {
5  console.log(`🚀 Server ready at ${url}`)
6})

Running our app

Ok, with our entrypoint setup, let's boot up dev mode and see what happens.

$npm run dev

You should also see a message indicating that your server is running, and where

$🚀 Server ready at http://localhost:4000

Try it out

Open it up, what do you see? It should be an instance of GraphQL Playground.

This is a graphical user interface for interacting with GraphQL APIs. If you prefer you can run a standalone version as an app on your machine, or another GraphQL GUI entirely. Nexus ships with one out of the box for your convenience.

Take a look at the right-hand side SCHEMA tab. There you'll see a default schema that Nexus has provided for you. This, along with the warning you saw before, will go away once you begin your own schema.

Note that Nexus will serve GraphQL requests on this same path. Only client GET requests with the accept: text/html header will get back the Playground response.

Wrapping up

That's it! In the next chapter you'll begin working on your app's schema.