mercurius-codegen

mercurius-codegen

Get full type-safety and autocompletion for Mercurius using TypeScript and GraphQL Code Generator seamlessly while you code.

pnpm add mercurius-codegen
pnpm add -D prettier
# or
yarn add mercurius-codegen
yarn add -D prettier
# or
npm install mercurius-codegen
npm install -D prettier

Usage

For convenience, this package also exports a fake gql tag that gives tooling support for "prettier formatting" and "IDE syntax highlighting". It's completely optional.

import Fastify from 'fastify'
import mercurius from 'mercurius'
import { codegenMercurius, gql } from 'mercurius-codegen'

const app = Fastify()

app.register(mercurius, {
  schema: gql`
    type Query {
      hello(greetings: String!): String!
    }
  `,
  resolvers: {
    Query: {
      hello(_root, { greetings }) {
        // greetings ~ string
        return 'Hello World'
      },
    },
  },
})

codegenMercurius(app, {
  targetPath: './src/graphql/generated.ts',
}).catch(console.error)

// Then it will automatically generate the file,
// and without doing anything special,
// the resolvers are going to be typed,
// or if your resolvers are in different files...

app.listen(8000)

import { IResolvers } from 'mercurius'

// Fully typed!
export const resolvers: IResolvers = {
  Query: {
    hello(_root, { greetings }) {
      // greetings ~ string
      return 'Hello World'
    },
  },
}

It also gives type-safety for Mercurius Loaders:

import { MercuriusLoaders } from 'mercurius'

// Fully typed!
export const loaders: MercuriusLoaders = {
  Dog: {
    async owner(queries, ctx) {
      // queries & ctx are typed accordingly
      return queries.map(({ obj, params }) => {
        // obj & params are typed accordingly
        return owners[obj.name]
      })
    },
  },
}

By default it disables itself if NODE_ENV is 'production'

It automatically uses prettier resolving the most nearby config for you.

Operations

mercurius-codegen also supports giving it GraphQL Operation files, basically client queries, mutations or subscriptions, and it creates Typed Document Nodes, that later can be used by other libraries, like for example mercurius-integration-testing (that has native support for typed document nodes), and then be able to have end-to-end type-safety and auto-completion.

You might need to install @graphql-typed-document-node/core manually in your project.

import { codegenMercurius } from 'mercurius-codegen'

codegenMercurius(app, {
  targetPath: './src/graphql/generated.ts',
  // You can also specify an array of globs
  operationsGlob: './src/graphql/operations/*.gql',
}).catch(console.error)

/your-project/src/graphql/operations/example.gql

query hello {
  HelloWorld
}

Then, for example, in your tests:

import { createMercuriusTestClient } from 'mercurius-integration-testing'

import { helloDocument } from '../src/graphql/generated'
import { app } from '../src/server'

// ...

const client = createMercuriusTestClient(app)

const response = await client.query(helloDocument)

// response is completely typed!

Keep in mind that you can always call codegenMercurius multiple times for different environments and different paths if you prefer to keep the production code as light as possible (which is generally a good practice).

LazyPromise

This library also exports a very lightweight helper that is very useful for lazy resolution of promises, for example, to prevent un-requested data to be fetched from a database.

Basically, it creates a lazy promise that defers execution until it's awaited or when .then() / .catch() is called, perfect for GraphQL Resolvers.

Internally, it uses p-lazy, which is also re-exported from this library

import { LazyPromise } from 'mercurius-codegen'

// ...

// users == Promise<User[]>
const users = LazyPromise(() => {
  return db.users.findMany({
    // ...
  })
})

Options

There are some extra options that can be specified:

interface CodegenMercuriusOptions {
  /**
   * Specify the target path of the code generation.
   *
   * Relative to the directory of the executed script if targetPath isn't absolute
   * @example './src/graphql/generated.ts'
   */
  targetPath: string
  /**
   * Disable the code generation manually
   *
   * @default process.env.NODE_ENV === 'production'
   */
  disable?: boolean
  /**
   * Don't notify to the console
   */
  silent?: boolean
  /**
   * Specify GraphQL Code Generator configuration
   * @example
   * codegenConfig: {
   *    scalars: {
   *        DateTime: "Date",
   *    },
   * }
   */
  codegenConfig?: CodegenPluginsConfig
  /**
   * Add code at the beginning of the generated code
   */
  preImportCode?: string
  /**
   * Operations glob patterns
   */
  operationsGlob?: string[] | string
  /**
   * Watch Options for operations GraphQL files
   */
  watchOptions?: {
    /**
     * Enable file watching
     *
     * @default false
     */
    enabled?: boolean
    /**
     * Extra Chokidar options to be passed
     */
    chokidarOptions?: ChokidarOptions
    /**
     * Unique watch instance
     *
     * `Especially useful for hot module replacement environments, preventing memory leaks`
     *
     * @default true
     */
    uniqueWatch?: boolean
  }
  /**
   * Write the resulting schema as a `.gql` or `.graphql` schema file.
   *
   * If `true`, it outputs to `./schema.gql`
   * If a string it specified, it writes to that location
   *
   * @default false
   */
  outputSchema?: boolean | string
}

codegenMercurius(app, {
  targetPath: './src/graphql/generated.ts',
  operationsGlob: ['./src/graphql/operations/*.gql'],
  disable: false,
  silent: true,
  codegenConfig: {
    scalars: {
      DateTime: 'Date',
    },
  },
  preImportCode: `
  // Here you can put any code and it will be added at very beginning of the file
  `,
  watchOptions: {
    enabled: true,
  },
  outputSchema: true,
}).catch(console.error)

GraphQL Schema from files

As shown in the examples/codegen-gql-files, you can load all your schema type definitions directly from GraphQL .gql files, and this library gives you a function that eases that process, allowing you to get the schema from files, watch for changes and preloading the schema for production environments.

• Usage options

export interface LoadSchemaOptions {
  /**
   * Watch options
   */
  watchOptions?: {
    /**
     * Enable file watching
     * @default false
     */
    enabled?: boolean
    /**
     * Custom function to be executed after schema change
     */
    onChange?: (schema: string[]) => void
    /**
     * Extra Chokidar options to be passed
     */
    chokidarOptions?: ChokidarOptions
    /**
     * Unique watch instance
     *
     * `Especially useful for hot module replacement environments, preventing memory leaks`
     *
     * @default true
     */
    uniqueWatch?: boolean
  }
  /**
   * Pre-build options
   */
  prebuild?: {
    /**
     * Enable use pre-built schema if found.
     *
     * @default process.env.NODE_ENV === "production"
     */
    enabled?: boolean
  }
  /**
   * Don't notify the console
   */
  silent?: boolean
}

import Fastify from 'fastify'
import mercurius from 'mercurius'
import { buildSchema } from 'graphql'
import { codegenMercurius, loadSchemaFiles } from 'mercurius-codegen'

const app = Fastify()

const { schema } = loadSchemaFiles('src/graphql/schema/**/*.gql', {
  watchOptions: {
    enabled: process.env.NODE_ENV === 'development',
    onChange(schema) {
      app.graphql.replaceSchema(buildSchema(schema.join('\n')))
      app.graphql.defineResolvers(resolvers)

      codegenMercurius(app, {
        targetPath: './src/graphql/generated.ts',
        operationsGlob: './src/graphql/operations/*.gql',
      }).catch(console.error)
    },
  },
})

app.register(mercurius, {
  schema,
  // ....
})

License

MIT