Nexus Documentation

Welcome!

Robust, composable type definition for GraphQL in TypeScript/JavaScript.

Note: The documentation is very new and may contain some gaps, please help us fill them in by opening issues or better yet, pull-requests when you think something could be explained better. The examples are a great place to look to better understand how the library can be used.

Nexus aims to combine the simplicity and ease of development of SDL development approaches like graphql-tools with the long-term maintainability of programmatic construction, as seen in graphene-python, graphql-ruby, or graphql-js.

Nexus builds upon the primitives of graphql-js, and attempts to take the simplicity of the SDL schema-first approach and pair it with the power of having the full language runtime at your disposal.

Nexus was designed with TypeScript/JavaScript intellisense in mind, and combines TypeScript generics, conditional types, and type merging to provide full auto-generated type coverage out of the box.

Check out the example projects to get some ideas of what this looks like in practice, or try it out in the playground to see what we mean!

Installation

1npm install nexus
2npm install graphql # required as a peer dependency

If you are using TypeScript version 4.1 is suggested. Nexus doesn't have a hard requirement for it yet but may in a future non-breaking release.

Example

As documented in the API reference GraphQL Nexus provides a consistent, scalable approach to defining GraphQL types in code.

1import {
2  arg,
3  enumType,
4  intArg,
5  interfaceType,
6  makeSchema,
7  objectType,
8  queryType,
9  stringArg,
10  list,
11} from 'nexus'
12
13const Node = interfaceType({
14  name: 'Node',
15  definition(t) {
16    t.id('id', { description: 'Unique identifier for the resource' })
17  },
18})
19
20const Account = objectType({
21  name: 'Account',
22  isTypeOf(source) {
23    return 'email' in source
24  },
25  definition(t) {
26    t.implements(Node) // or t.implements("Node")
27    t.string('username')
28    t.string('email')
29  },
30})
31
32const StatusEnum = enumType({
33  name: 'StatusEnum',
34  members: ['ACTIVE', 'DISABLED'],
35})
36
37const Query = queryType({
38  definition(t) {
39    t.field('account', {
40      type: Account, // or "Account"
41      args: {
42        name: stringArg(),
43        status: arg({ type: 'StatusEnum' }),
44      },
45    })
46    t.field('accountsById', {
47      type: list(Account), // or "Account"
48      args: {
49        ids: list(intArg()),
50      },
51    })
52  },
53})
54
55// Recursively traverses the value passed to types looking for
56// any valid Nexus or graphql-js objects to add to the schema,
57// so you can be pretty flexible with how you import types here.
58const schema = makeSchema({
59  types: [Account, Node, Query, StatusEnum],
60  // or types: { Account, Node, Query }
61  // or types: [Account, [Node], { Query }]
62})