nitrogql

Monorepo Guide

This page guides you how to configure nitrogql for monorepo projects. In a monorepo setting, you may have GraphQL schema and operations in different packages. This guide shows you how to use nitrogql in such projects.

Basically you set up nitrogql in each package that contains GraphQL files. Appropriate configuration for schema packages and operation packages are different.

Schema Package

Here, we assume that you have a package that contains your GraphQL schema.

In such package, you only generate code for the schema. Your configuration file should look like:

schema: ./schema/*.graphql
extensions:
  nitrogql:
    generate:
      schemaOutput: ./dist/schema.d.ts

💡 See Configuration Options for all available options.

By running nitrogql generate, you will get a schema.d.ts file in the dist directory.

The schema package should export the generated schema types so that other packages can use them. You can do this by exporting the generated schema types from the the package.

// packages/schema-package/index.ts
export * from "./dist/schema";

Operation Packages

In the operation packages, you generate code for operations. Your configuration file should look like:

schema: ../schema-package/schema/*.graphql
documents: ./app/**/*.graphql
extensions:
  nitrogql:
    generate:
      schemaModuleSpecifier: "@your-org/schema-package"

Note that the schema option is still required, and should point to .graphql files that contain the schema definitions. You need to use relative paths that go beyond the package boundary.

You must also specify the schemaModuleSpecifier option. This option tells nitrogql to import the generated schema types using the specified module specifier. This option is required if you want to only generate code for operations.

By running nitrogql generate, you will get TypeScript files generated next to your GraphQL files.

As the schemaModuleSpecifier option suggests, operation packages will depend on the schema package.

GraphQL Server Packages

A GraphQL server package is one that contains the GraphQL server implementation. This may or may not be the same package as the schema package. Typically you define resolvers in this package, so that your server knows how to handle GraphQL operations.

In this kind of package, you utilize resolver types generated by nitrogql. Your configuration file should look like:

schema: ../schema-package/schema/*.graphql
extensions:
  nitrogql:
    plugins:
      - "nitrogql:model-plugin"
    generate:
      schemaModuleSpecifier: "@your-org/schema-package"
      resolversOutput: ./dist/resolvers.d.ts
      serverGraphqlOutput: ./dist/graphql.ts

By running nitrogql generate, you will get a resolvers.d.ts file and a graphql.ts file in the dist directory.

Please refer to the guide for using generated types from server code for how to use the generated code.