The Guild LogoThe Guild Monogram

Search docs

Search icon

Products by The Guild

Products

Hive logoHive blurred logo

Hive

Schema Registry for your GraphQL Workflows

Docs

GraphQL Code Generator

Generate anything from GraphQL schema / operations!

Contact Us

Programmatic Usage#

The codegen has also a complete programmatic API. You can use it if you need to customize the execution flow, or if you are writing a tool that uses the codegen.

Basic Programmatic Usage#

In order to use the programmatic API, start by importing codegen from @graphql-codegen/core:

import { codegen } from '@graphql-codegen/core'

Then, create a configuration object (complete signature):

import { buildSchema, printSchema, parse, GraphQLSchema } from 'graphql' import * as fs from 'fs' import * as path from 'path' import * as typescriptPlugin from '@graphql-codegen/typescript' const schema: GraphQLSchema = buildSchema(`type A { name: String }`) const outputFile = 'relative/pathTo/filename.ts' const config = { documents: [], config: {}, // used by a plugin internally, although the 'typescript' plugin currently // returns the string output, rather than writing to a file filename: outputFile, schema: parse(printSchema(schema)), plugins: [ // Each plugin should be an object { typescript: {} // Here you can pass configuration to the plugin } ], pluginMap: { typescript: typescriptPlugin } }

The schema field be a valid GraphQLSchema object. If you need to load your GraphQL schema from an external source (file, url), you can use loadSchema from @graphql-tools/load.

Notice that a plugin name key in pluginMap and plugins must match to identify a plugin and its configuration.

You need to import the plugin in your favorite way, you can also use await import to lazy load it.

Then, provide the config object to codegen:

const output = await codegen(config) fs.writeFile(path.join(__dirname, outputFile), output, () => { console.log('Outputs generated!') })
info#

We are using this API in the live demo in GraphQL Code Generator website. The code is here.

Loading schema and documents#

You can use one of the tools from @graphql-tools for file loading, schema merging, transformations and more.

Using the CLI instead of core#

If you wish to have the benefits that cli package has (like loading schema and document files, parsing endpoints and more), you can use require() (or import) for @graphql-codegen/cli directly with Node.JS:

import { generate } from '@graphql-codegen/cli' async function doSomething() { const generatedFiles = await generate( { schema: 'http://127.0.0.1:3000/graphql', documents: './src/**/*.graphql', generates: { [process.cwd() + '/models/types.d.ts']: { plugins: ['typescript'] } } }, true ) }

The return value should be of type Promise<FileOutput[]>.

caution#

This usage will not work in a browser environment, because the cli package depends on NodeJS internals and the file system.