nitrogql 1.3 release: GraphQL Scalars support

Published at October 8, 2023

Today, we are happy to announce release of nitrogql 1.3!

nitrogql is a toolchain for using GraphQL in TypeScript projects. In 1.3, we added a new built-in plugin for integrating with GraphQL Scalars.

Integrating with GraphQL Scalars

GraphQL Scalars is a library that provides a set of useful custom scalar types for GraphQL. Before 1.3, you could use GraphQL Scalars with nitrogql, but you had to manually define corresponding TypeScript types with the scalarTypes option.

With the new built-in plugin, nitrogql:graphql-scalars-plugin, you can use GraphQL Scalars without manually defining custom scalar types. The plugin automatically recognizes suitable TypeScript types for GraphQL Scalars types.

Usage

To use the plugin, you need to add it to the plugins array in the configuration file.

schema:
  - ./schema/*.graphql
  - ./schema/scalars.ts
extensions:
  nitrogql:
    plugins:
      - "nitrogql:graphql-scalars-plugin"
    # ...

In the above example, ./schema/scalars.ts is a TypeScript file that includes the GraphQL Scalars types. This file will look like:

import { GraphQLSchema } from "graphql";
import { DateTimeResolver } from "graphql-scalars";

export default new GraphQLSchema({
  types: [DateTimeResolver],
});

With this configuration, nitrogql will automatically recognize DateTime as a scalar type. You can use it in your GraphQL schema without additional configuration.

The exact work done by the plugin is to examine each GraphQLScalarType instance in the schema and find a corresponding TypeScript type in extensions.codegenScalarType. This data enables an automatic mapping from GraphQL Scalars types to TypeScript types by GraphQL toolings.

This also means that other libraries that provide custom scalar types could also be supported by nitrogql as long as they provide a GraphQLScalarType instance with the extensions.codegenScalarType metadata. We are not aware of any other libraries that provide such metadata though.

At runtime, you should reuse the GraphQLSchema instance you supplied to nitrogql. To do so, merge that instance with the other parts of your schema and your resolver implementations. @graphql-tools/schema provides a convenient way to do so. For example:

import { mergeSchemas } from "@graphql-tools/schema";

// GraphQLSchema object for scalars
import schema from "../../schema/scalar";

// Generated by nitrogql
import { schema as typeDefs } from "@/generated/graphql";
import { Resolvers } from "@/generated/resolvers";

type Context = {};
const resolvers: Resolvers<{}> = {
  // ...
};

const server = new ApolloServer({
  schema: mergeSchemas({
    schemas: [schema],
    typeDefs,
    resolvers,
  }),
});

See our Next.js example for a working example.

Conclusion

In this release, we improved support for GraphQL Scalars. With a new built-in plugin, you can use GraphQL Scalars without manually defining custom scalar types. Just include the GraphQL Scalars types in your GraphQLSchema object and that's it!

Having a single source of truth is always preferable. Custom scalar types are no exception. Therefore, it is good idea for libraries to provide such metadata so that the runtime implementation and the TypeScript type definition are always in sync. This release is a significant step towards that direction.

nitrogql is developed by uhyo. Contribution is more than welcome!