nitrogql logonitrogql

Configuration Options

This page describes all the configuration options available in the configuration file.

💡 The file format follows the GraphQL Config convention from The Guild. This enables you to share the configuration file with other GraphQL tools, if you use any.

💡 Relative paths are always resolved from the location of the configuration file.

schema and operations

To specify the location of your schema and operations, use schema and documents top-level fields. These fields accept glob patterns and can be specified as a string or an array of strings.

schema: "./schema/*.graphql"
documents:
  - "./app/**/*.graphql"
  - "./common/**/*.graphql"

Note that schema and operations are parsed with different parsers. Mixing them will cause errors.

schema is always required. documents is optional. If you only have schema, you can still use nitrogql to check your schema.

Schema file types

Nitrogql supports three types of schema files:

Nitrogql automatically detects the type of the schema file based on the file extension.

A .js/.ts schema file must default-export schema either as a string or as a GraphQLSchema object.

Operation file type

Nitrogql only supports .graphql files for operations.

💡 Other configuration options are placed under extensions.nitrogql in the configuration file.

plugins

The plugins field is used to configure which plugins to use.

Currently, third-party plugins are not supported. You can only use built-in plugins. Available plugins are:

Example:

extensions:
  nitrogql:
    plugins:
      - nitrogql:model-plugin

generate.schemaOutput

Where to output the generated schema types. Generated file is depended by generated operations types.

If you do not specify generate.schemaOutput:

Example:

schema: "./schema/*.graphql"
documents:
  - "./app/**/*.graphql"
  - "./common/**/*.graphql"
extensions:
  nitrogql:
    generate:
      schemaOutput: "./app/generated/schema.ts"

generate.serverGraphqlOutput

When set, the generate command will generate a single TypeScript file which contains the entire GraphQL schema. This file can be used to create a GraphQL server.

Example:

schema: "./schema/*.graphql"
documents:
  - "./app/**/*.graphql"
extensions:
  nitrogql:
    generate:
      serverGraphqlOutput: "./app/generated/graphql.ts"

With the above configuration, the generated code will look like:

// ./app/generated/graphql.ts
export const schema = `
scalar String
scalar Boolean
# ...
type Query {
  # ...
}
# ...
`;

generate.resolversOutput

When set, the generate command will generate a single TypeScript file which contains type definitions for resolvers. This is helpful for writing resolvers in a type-safe manner.

This file depends on the generated schema types. Therefore, you need to configure either generate.schemaOutput or generate.schemaModuleSpecifier to use this option.

Example:

schema: "./schema/*.graphql"
extensions:
  nitrogql:
    generate:
      resolversOutput: "./app/generated/resolvers.ts"

generate.mode

Configures how types for operations are generated. Possible values are:

Example:

schema: "./schema/*.graphql"
documents:
  - "./app/**/*.graphql"
  - "./common/**/*.graphql"
extensions:
  nitrogql:
    generate:
      mode: with-loader-ts-5.0
      schemaOutput: "./app/generated/schema.ts"

with-loader-ts-5.0

Generates type definitions compatible with TypeScript 5.0 and above. This mode is recommended for projects using TypeScript 5.0 or above.

This mode generates foo.d.graphql.ts next to foo.graphql which allows importing foo.graphql as a module.

💡 With this mode, you need to configure tsconfig.json to enable the allowArbitraryExtensions compiler option.

In order to import .graphql files as modules, you also need to configure your bundler to handle .graphql files. See Getting Started.

with-loader-ts-4.0

Generates type definitions compatible with TypeScript 4.x.

This mode generates foo.graphql.d.ts next to foo.graphql which allows importing foo.graphql as a module.

In order to import .graphql files as modules, you also need to configure your bundler to handle .graphql files. See Getting Started.

standalone-ts-4.0

Generates TypeScript coe compatible with TypeScript 4.x. This mode is recommended for projects which don't use bundlers.

This mode generates foo.graphql.ts next to foo.graphql which allows importing foo.graphql.ts as a module. The generated code includes runtime code so you do not need to configure your bundler.

generate.schemaModuleSpecifier

Configures what module specifier to use when importing the generated schema types from operations types. When set, all generated operations types will import the schema types from this exact module name. If not set, the generated operations types will import the schema types using relative paths.

This option is especially useful in monorepo projects where you need to import the schema types from a different package.

Example:

schema: "./schema/*.graphql"
documents:
  - "./app/**/*.graphql"
  - "./common/**/*.graphql"
extensions:
  nitrogql:
    generate:
      schemaOutput: "./app/generated/schema.ts"
      schemaModuleSpecifier: "@/generated/schema"

With the above configuration, the generated operations types will import the schema types from @/generated/schema so they will look like:

import * as Schema from "@/generated/schema";
// ...

Note that you also need to configure your bundler to resolve @/generated/schema correctly (to app/generated/schema.ts).

generate.emitSchemaRuntime

If true, emit runtime code for generated schema types (one specified by generate.schemaOutput). Default is false.

Currently, runtime code is emitted only for enums.

⚠️ If you set this option to true, the schemaOutput file cannot be a .d.ts file.

Example:

extensions:
  nitrogql:
    generate:
      schemaOutput: "./app/generated/schema.ts"
      emitSchemaRuntime: true

With the above configuration, the generated schema code will look like:

// Always emitted for enums
export type UserType = "NormalUser" | "PremiumUser";
// Emitted only if emitSchemaRuntime is true
export const UserType = {
  NormalUser: "NormalUser",
  PremiumUser: "PremiumUser",
} as const;

generate.type

Set of configurations about details of generated types.

Default settings are:

extensions:
  nitrogql:
    generate:
      type:
        # default values
        scalarTypes: {}
        allowUndefinedAsOptionalInput: true

scalarTypes

Configures how GraphQL scalar types are mapped to TypeScript types. The default mapping is:

scalarTypes:
  ID:
    send: string | number
    receive: string
  String: string
  Boolean: boolean
  Int: number
  Float: number

If you declare a custom scalar type in your schema, you must specify the mapping in the configuration file. Any TypeScript code is allowed as long as it is valid as a type.

💡 If you are using the nitrogql:graphql-scalars-plugin, you do not need to specify the mapping for GraphQL Scalars types you are using.

Mapping for built-in scalar types need not be specified unless you want to override them.

Example:

extensions:
  nitrogql:
    generate:
      type:
        scalarTypes:
          Date: string

Note that nitrogql supports three different ways to specify the mapping:

scalarTypes:
  # 1. Specify as a single string
  Date: string
  # 2. Specify as a pair of send and receive types
  Date:
    send: string | Date
    receive: string
  # 3. Specify as a set of four types
  Date:
    resolverInput: string
    resolverOutput: string | Date
    operationInput: string | Date
    operationOutput: string

Read more at Configuring Scalar Types.

allowUndefinedAsOptionalInput

In GraphQL, there is no explicit concept of optional fields. Instead, you use fields of nullable types to represent optional fields.

If this option is set to true, undefined is allowed as an input value for nullable fields. This also implies that you can omit optional fields.

If this option is set to false, you must explicitly provide null for optional fields.

This option affects input types (those defined with GraphQL's input keyword) and operation variables. This option defaults to true.

generate.name

Set of configurations about names of generated variables and types.

Default settings are:

extensions:
  nitrogql:
    generate:
      name:
        # default values
        capitalizeOperationNames: true
        operationResultTypeSuffix: Result
        variablesTypeSuffix: Variables
        fragmentTypeSuffix: ''
        queryVariableSuffix: Query
        mutationVariableSuffix: Mutation
        subscriptionVariableSuffix: Subscription
        fragmentVariableSuffix: ''

capitalizeOperationNames

If true, capitalize the first letter of operation names. Default is true.

This option can control how generated operation document can be imported via auto import feature of your editor. For example, if you have query getUser in your schema, it can be auto-imported by typing GetUserQuery in your code.

import GetUserQuery from "./app/graphql/queries/getUser.graphql";

If you set capitalizeOperationNames: false, the generated operation document can be imported by typing getUserQuery instead.

operationResultTypeSuffix

Suffix of the operation result type. Default is "Result".

For example, if you have query getUser in your schema, the generated operation result type will be GetUserResult.

💡 Operation result type is not visible unless you set export.operationResultType to true.

variablesTypeSuffix

Suffix of the operation variables type. Default is "Variables".

For example, if you have query getUser in your schema, the generated operation variables type will be GetUserVariables.

💡 Operation variables type is not visible unless you set export.operationResultType to true.

fragmentTypeSuffix

Suffix of the fragment type. Default is "".

For example, if you have fragment PartialUser in your schema, the generated fragment type will be PartialUserFragment.

queryVariableSuffix

Suffix of the query variable. Default is "Query".

For example, if you have query getUser in your schema, the generated query variable will be GetUserQuery.

mutationVariableSuffix

Suffix of the mutation variable. Default is "Mutation".

For example, if you have mutation createUser in your schema, the generated mutation variable will be CreateUserMutation.

subscriptionVariableSuffix

Suffix of the subscription variable. Default is "Subscription".

For example, if you have subscription onUserCreated in your schema, the generated subscription variable will be OnUserCreatedSubscription.

fragmentVariableSuffix

Suffix of the fragment variable. Default is "".

generate.export

Set of configurations about how generated code should export generated types and variables. Default settings are:

extensions:
  nitrogql:
    generate:
      export:
        defaultExportForOperation: true
        operationResultType: false
        variablesType: false

defaultExportForOperation

If true, a generated operation document will be exported as a default export. Default is true.

For example, if you have query getUser in your schema, the generated operation document will be exported as a default export so that you can import it like:

// defaultExportForOperation: true
import GetUserQuery from "./app/graphql/queries/getUser.graphql";

If you set defaultExportForOperations: false, the generated operation document will be exported as a named export so that you can import it like:

// defaultExportForOperation: false
import { GetUserQuery } from "./app/graphql/queries/getUser.graphql";

operationResultType

If true, a generated operation result type will be exported. Default is false.

For example, if you have query getUser in your schema, the generated operation result type will be exported so that you can import it like:

// operationResultType: true
import { GetUserResult } from "./app/graphql/queries/getUser.graphql";

💡 You can also use ResultOf from the @graphql-typed-document-node/core package to extract the result type from your operation document.

variablesType

If true, a generated operation variables type will be exported. Default is false.

For example, if you have query getUser in your schema, the generated operation variables type will be exported so that you can import it like:

// variablesType: true
import { GetUserVariables } from "./app/graphql/queries/getUser.graphql";

💡 You can also use VariablesOf from the @graphql-typed-document-node/core package to extract the variables type from your operation document.