API

makeSchema

makeSchema

Defines the GraphQL schema, by combining the GraphQL types defined by the GraphQL Nexus layer or any manually defined GraphQL named types (Scalars, ObjectTypes, Enums, etc).

We require at least one type be named "Query", which will be used as the root query type. The makeSchema takes several options which all should be specified by the user, detailed below:

types

The types property is required, and should contain all of the possible Nexus/GraphQL types that make up a schema (at least the root-level ones), imported into one place. The type is opaque, it can be an array or object, we recursively walk through the object looking for types, so the following will all have the same result, and non-GraphQL objects will be ignored.

  • { typeA, typeB, typeC, typeD }
  • [[typeA], [{ typeB: typeB }], typeC, { typeD }]
  • [typeA, typeB, typeC, typeD]
1import { makeSchema } from 'nexus'
2import * as types from './allNexusTypes'
3
4export const schema = makeSchema({
5 types,
6})

plugins

The plugins property is an array for adding "Plugins", or ways of extending/changing the runtime behavior of Nexus and GraphQL. Unlike the types property, this must be an array, and the order of the plugins matters because this influences the order of any resolver "middleware" the plugin may optionally provide.

1import { makeSchema, nullabilityGuard, fieldAuthorizePlugin } from 'nexus'
2import * as types from './allNexusTypes'
3
4export const schema = makeSchema({
5 types,
6 plugins: [
7 fieldAuthorizePlugin({
8 /* ... */
9 }),
10 nullabilityGuard({
11 /* ... */
12 }),
13 ],
14})

shouldGenerateArtifacts, outputs, sourceTypes

The shouldGenerateArtifacts is a boolean value which determines whether artifact files (graphql and TypeScript) are emitted when the code for makeSchema

outputs is an object which specifies the absolute path for where the emitted files are generated. If you do not wish to generate one of these types

sourceTypes is an object which gives nexus more information about how to properly generate the type definition file. An example of the usage is provided below:

1makeSchema({
2 types,
3 shouldGenerateArtifacts: process.env.NODE_ENV === 'development',
4 outputs: {
5 // I tend to use `.gen` to denote "auto-generated" files, but this is not a requirement.
6 schema: path.join(__dirname, 'generated/schema.gen.graphql'),
7 typegen: path.join(__dirname, 'generated/nexusTypes.gen.ts'),
8 },
9 sourceTypes: {
10 headers: [
11 'import { ConnectionFieldOpts } from "@packages/api-graphql/src/extensions/connectionType"',
12 ],
13 modules: [
14 // Automatically finds any interface/type/class named similarly to the and infers it
15 // the "source" type of that resolver.
16 {
17 module: '@packages/types/src/db.ts',
18 alias: 'dbt',
19 typeMatch: name => new RegExp(`(?:interface|type|class)\\s+(${name}s?)\\W`, 'g'),
20 },
21 ],
22 // Typing for the GraphQL context
23 contextType: {
24 module: '@packages/data-context/src/DataContext.ts',
25 alias: 'ctx',
26 },
27 mapping: {
28 Date: 'Date',
29 DateTime: 'Date',
30 UUID: 'string',
31 },
32 debug: false,
33 },
34})

The Ghost Example is the best place to look for an example of how we're able to capture the types from existing runtime objects or definitions and merge them with our schema.

shouldExitAfterGenerateArtifacts

If you are not checking in your artifacts and wish to run them, this will allow you to exit right after the artifacts have been generated. There is no default behavior for this, but you could do something like the following, to be able to run a script which will exit if --nexus-exit is provided:

1makeSchema({
2 // ... options like above
3 shouldExitAfterGenerateArtifacts: process.argv.includes('--nexus-exit'),
4})
1ts-node -T ./path/to/my/schema.ts --nexus-exit

prettierConfig

Either an absolute path to a .prettierrc file, or an object with a valid "prettier" config options.

1makeSchema({
2 // ... options like above
3 prettierConfig: path.join(__dirname, '../../../.prettierrc'),
4})

nonNullDefaults

Controls the nullability of the input / output types emitted by nexus. The current Nexus default is { output: true, input: false }, though the graphql-js / spec default is { output: false, input: false }.

You should make a decision on this and supply the option yourself, it may be changed / required in the future.

Read more on this in the getting-started guide.

typegenConfig, formatTypegen

Escape hatches for more advanced cases which need further control over. You typically won't need these.

customPrintSchemaFn

Optional, allows you to override the printSchema when outputting the generated .graphql file:

1makeSchema({
2 // ...
3 customPrintSchemaFn: schema => {
4 return printSchema(schema, { commentDescriptions: true })
5 },
6})

Footnotes: Annotated config option for sourceTypes:

1export interface SourceTypesConfigOptions {
2 /** Any headers to prefix on the generated type file */
3 headers?: string[]
4 /**
5 * Array of SourceTypeModule's to look in and match the type names against.
6 *
7 * @example
8 * modules: [
9 * { module: 'typescript', alias: 'ts' },
10 * { module: path.join(__dirname, '../sourceTypes'), alias: 'b' },
11 * ]
12 */
13 modules: SourceTypeModule[]
14 /**
15 * Types that should not be matched for a source type,
16 *
17 * By default this is set to ['Query', 'Mutation', 'Subscription']
18 *
19 * @example
20 * skipTypes: ['Query', 'Mutation', /(.*?)Edge/, /(.*?)Connection/]
21 */
22 skipTypes?: (string | RegExp)[]
23 /**
24 * If debug is set to true, this will log out info about all types found, skipped, etc. for the type
25 * generation files. @default false
26 */
27 debug?: boolean
28 /**
29 * If provided this will be used for the source types rather than the auto-resolve mechanism above. Useful
30 * as an override for one-off cases, or for scalar source types.
31 */
32 mapping?: Record<string, string>
33}
34
35export interface SourceTypeModule {
36 /**
37 * The module for where to look for the types.
38 * This uses the node resolution algorithm via require.resolve,
39 * so if this lives in node_modules, you can just provide the module name
40 * otherwise you should provide the absolute path to the file.
41 */
42 module: string
43 /**
44 * When we import the module, we use 'import * as ____' to prevent
45 * conflicts. This alias should be a name that doesn't conflict with any other
46 * types, usually a short lowercase name.
47 */
48 alias: string
49 /**
50 * Provides a custom approach to matching for the type
51 *
52 * If not provided, the default implementation is:
53 *
54 * (type) => [
55 * new RegExp(`(?:interface|type|class|enum)\\s+(${type.name})\\W`, "g")
56 * ]
57 *
58 */
59 typeMatch?: (type: GraphQLNamedType, defaultRegex: RegExp) => RegExp | RegExp[]
60 /**
61 * A list of typesNames or regular expressions matching type names
62 * that should be resolved by this import. Provide an empty array if you
63 * wish to use the file for context and ensure no other types are matched.
64 */
65 onlyTypes?: (string | RegExp)[]
66 /**
67 * By default the import is configured 'import * as alias from', setting glob to false
68 * will change this to 'import alias from'
69 */
70 glob?: false
71}
Edit this page on Github