npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@a0viedo/mercurius-codegen

v5.0.3

Published

[![npm version](https://badge.fury.io/js/mercurius-codegen.svg)](https://badge.fury.io/js/mercurius-codegen)

Downloads

7

Readme

mercurius-codegen

npm version

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