nitrogql

Schema file reference

The schema type definition file is used to express your GraphQL schema as TypeScript types. It is generated by the nitrogql generate command and written to the path specified by the generate.schemaOutput option.

This file is depended by other files generated by nitrogql. Also, you might want to import it in your own code to use the generated types.

Exported Types

The schema type definition file exports a TypeScript type for each GraphQL type defined in your schema ( scalar, object, interface, union, enum, and input object) with the same name.

Note that the types define here basically correspond to the result of GraphQL operations. Therefore, it is not suited for use by server-side code. See Resolvers type file reference for the types usable by server-side code.

Scalar Types

TypeScript type for a scalar type is determined by the generate.type.scalarTypes option.

Object Types

TypeScript type for an object type is an object type. It has a property for each field of the object type. Fields with nullable GraphQL type are also nullable (| null) in TypeScript. Note that nullable fields are not optional (field?: ...) in TypeScript.

Note that the exported types also have the __typename field.

Interface Types and Union Types

TypeScript type for an interface type or a union type is a union type of object types that implement the interface or are included in the union.

Enum Types

TypeScript type for an enum type is a union of string literals types that correspond to the enum values.

By default, the type definition file only exports the type. If you configure the generate.emitSchemaRuntime option, it also exports a runtime representation of the enum type.

Input Object Types

TypeScript type for an input object type is an object type. Unlike (output) object types, nullable fields are also made optional in corresponding TypeScript types.

Best Practices

Except for the runtime representation of enum types (if you like), you rarely need to import from this file directly. Particularly, it is not a good idea to use types defined in this file for internal data structures. Instead, you should use manually written types for internal data structures.

// ❌ Don't do this
import { User } from "@your-org/schema-package";
export const ShowUser: React.FC<{
  user: User;
}> = ({ user }) => {
  // ...
};

// ✅ Do this
export const ShowUser: React.FC<{
  user: {
    id: string;
    name: string;
  };
}> = ({ user }) => {
  // ...
};

💡 This may change after a Fragment Colocation support has been implemented, though I am not quite convinced that Fragment Colocation is a good idea.