Nexus Documentation

By default, Nexus treats both inputs (arguments and input object fields) and outputs (object type fields) as nullable.

Implications of default nullability:

• Outputs: Being nullable allows you to change output requirements later without breaking clients, but requires client developers to handle null cases.
• Inputs: Being nullable makes the API easier for clients to consume (no upfront configuration required), but requires more careful design as making an input required later is a breaking change.
• TypeScript Types: When an input is nullable, the TypeScript type in your resolver will be null | undefined. null represents an explicit null passed by the client, while undefined represents the client omitting the input entirely.

The Nexus API is designed around four core principles to ensure a high-quality developer experience. When extending the API or suggesting changes, ensure they align with these goals:

1. Type-Safety: TypeScript type generation is provided by default.
2. Readability: The API structure should be easy to read and understand.
3. Developer ergonomics: The API should be intuitive and easy to use.
4. Prettier compatibility: The API is designed to work seamlessly with Prettier formatting.

Nexus uses a code-first approach, which differs from the traditional schema-first approach.

In a schema-first approach, you define a schema using GraphQL Schema Definition Language (SDL) and then write separate resolver logic to provide data. This often leads to context switching between SDL and JavaScript/TypeScript and requires keeping schema and resolvers in sync.

In the code-first approach used by Nexus, you write both the schema and the resolver logic in the same place using a single language (JavaScript or TypeScript). This ensures schema and resolver co-location and reduces the need for manual synchronization.

In Nexus (and GraphQL generally), there is a distinction between the API Types seen by the client and the Source Types used internally by resolvers.

When a field resolver returns an object, that object is the Source Type. This data is then passed as the first argument (source) to all subsequent field resolvers for that object type. This allows you to map raw database records (like a row from a SQL table) to a structured GraphQL schema.

For example, a Query.user resolver might fetch a database record containing { firstname: 'Foo', lastname: 'Bar' }. The User object type then uses this record as its source to resolve fields like fullName.

Nexus generates types that combine your schema, field configurations, and the GraphQL resolution algorithm to provide type safety with minimal manual annotation. Key concepts include:

• Root Types: The type representation of the value used to resolve fields (the first argument passed to resolve). This can be a plain JS object, a database model, a Mongoose document, or a JS class. For Relay-style pagination Edge types where no explicit backing type exists, Nexus generates an assumed type which can be overridden with a concrete type.
• Field Type: The valid return value for a field. Because GraphQL allows promises at any level, Nexus wraps these in a MaybePromiseDeep<T> type to represent potential asynchronous values.

The repository provides several examples categorized by language and complexity:

Featured TypeScript Example

• ghost-graphql: Demonstrates the use of schemats and inferred types.

JavaScript Examples

• githunt-api

TypeScript Examples

• ts-ast-reader
• apollo-fullstack
• star-wars
• kitchen-sink
• with-prisma (Note: This example requires manual setup via its own README and is not included in the bulk examples command).

To migrate a query like t.crud.posts() or t.crud.post(), define the field explicitly using t.field or t.nonNull.list.nonNull.field and define any required inputObjectType for arguments (e.g., PostWhereUniqueInput). Use the SDL Converter to assist in generating the necessary Nexus code from your existing GraphQL schema.

// Migrating t.crud.posts()
const Query = objectType({
  name: "Query",
  definition(t) {
    t.nonNull.list.nonNull.field("posts", {
      type: Post,
      args: {
        after: arg({ type: PostWhereUniqueInput }),
        before: arg({ type: PostWhereUniqueInput }),
        first: intArg(),
        last: intArg(),
      },
    })
  }
})

const PostWhereUniqueInput = inputObjectType({
  name: "PostWhereUniqueInput",
  definition(t) {
    t.int("id")
  }
});

To replicate the development experience of the Nexus Framework, use two separate processes: one for running the API (without type checking to avoid blocking the reflection system) and one for background type checking.

Add the following to your package.json scripts:

{
  "scripts": {
    "dev": "ts-node-dev --transpile-only ./your/main/module",
    "dev:typecheck": "tsc --noEmit --watch"
  }
}

• dev: Uses ts-node-dev to run your API. The --transpile-only flag is critical so that type errors do not halt the process, allowing the Nexus reflection system to generate schema types.
• dev:typecheck: Uses tsc in watch mode to provide static type checking in a separate terminal.

When using custom scalars, you must include the scalar in the types array of the makeSchema configuration to ensure it is part of the generated schema.

const schema = makeSchema({
  types: [GQLDate] // Add Scalar to Array
})

To ensure full type safety during the Next.js build process, you must run the Nexus type generation before next build. Add a dedicated typegen script to your package.json and update your build command to chain them together.

{
  "scripts": {
    "dev": "next dev",
    "build:nexus-typegen": "ts-node --compiler-options '{\"module\":\"CommonJS\"}' --transpile-only schema",
    "build": "npm run build:nexus-typegen && next build",
    "start": "next start"
  }
}

Create a tsconfig.json file in your project root to enable full TypeScript support for your Nexus project.

{
  "compilerOptions": {
    "target": "ES2018",
    "module": "commonjs",
    "lib": ["esnext"],
    "strict": true,
    "rootDir": ".",
    "outDir": "dist",
    "sourceMap": true,
    "esModuleInterop": true
  }
}