Skip to content

Latest commit

 

History

History
188 lines (102 loc) · 8.62 KB

codegen-config.md

File metadata and controls

188 lines (102 loc) · 8.62 KB
Raw
id title
codegen-config
codegen.yml

The Plugin Hub lists dozens of plugins with their set of options and specific outputs.

GraphQL Code Generator relies on a configuration file named codegen.yml or codegen.json to manage all possible options, input, and output document types.

The CLI automatically detects the defined config file and generates code accordingly.

In addition, you can also define a path to your config file with the --config options, like so:

<PackageRun scripts={['graphql-codegen --config ./path/to/config.yml']} />

 

 

Configuration file format

Here's an example for a possible config file:

schema: http://localhost:3000/graphql
documents: ./src/**/*.graphql
generates:
  ./src/types.ts:
    plugins:
      - typescript
      - typescript-operations

If you are looking for a reference file, an example for a large configuration file can be seen here.

:::tip For VSCode users Ensure to install the YAML plugin to add validation auto-complete capabilities for available plugins configuration files and codegen.yml file. :::

 

 

Configuration options

Here are the supported options that you can define in the config file (see source code):

  • schema (required) - A URL to your GraphQL endpoint, a local path to .graphql file, a glob pattern to your GraphQL schema files, or a JavaScript file that exports the schema to generate code from. This can also be an array that specifies multiple schemas to generate code from. You can read more about the supported formats here.

  • documents - Array of paths or glob patterns for files which export GraphQL documents using a gql tag or a plain string; for example: ./src/**/*.graphql. You can also provide these options with a string instead of an array if you're dealing with a single document. You can read more about the supported formats here.

  • generates (required) - A map where the key represents an output path for the generated code, and the value represents a set of relevant options for that specific file. Below are the possible options that can be specified:

    • generates.plugins (required) - A list of plugins to use when generating the file. Templates, considered as plugins, can be specified in this section. A complete list of supported plugins is available here. You can also point to a custom plugin in a local file (see Custom Plugins).

    • generates.preset - A list of presets to use for the output. Presets are a way to dynamically create the list of output files based on the input schema. near-operation-file-preset is a good example.

    • generates.schema - Same as root schema, but applies only for the specific output file.

    • generates.documents - Same as root documents, but applies only for the specific output file.

    • generates.config - Same as root config, but applies only for the specific output file.

    • generates.overwrite - Same as root overwrite, but applies only for the specific output file.

  • require - A path to a file which defines custom Node.JS require() handlers for custom file extensions. This option is essential if the code generator has to go through files that require other files in an unsupported format (more information). Note that values specified in your .yml file get loaded after loading the .yml file.

  • config - Options we would like to provide to the specified plugins. The options may vary depending on what plugins you specified. Read the documentation of that specific plugin for more information. You can read more about passing configuration to plugins here.

  • overwrite - A flag to overwrite files if they already exist when generating code (true by default).

  • watch - A flag to trigger codegen when there are changes in the specified GraphQL schemas. You can either specify a boolean to turn it on/off or specify an array of glob patterns to add custom files to the watch.

  • silent - A flag to suppress printing errors when they occur.

  • errorsOnly - A flag to suppress printing anything except errors.

  • hooks - Specifies scripts to run when events are happening in the codegen's core. You can read more about lifecycle hooks here. You can specify this on your root configuration or on each output.

  • pluginLoader - If you are using the programmatic API in a browser environment, you can override this configuration to load your plugins in a way different than require.

  • pluckConfig - Allows you to override the configuration for graphql-tag-pluck. This tool extracts your GraphQL operations from your code files.

    • pluckConfig.modules - An array of { name: string, identifier: string } uses to track down your gql usages and imports. Use this if your code files import gql from another library or have a custom gql tag. identifier is the named export, so don't provide it if the tag function is imported as default.

    • pluckConfig.gqlMagicComment - Configures the magic GraphQL comments to look for. The default is /* GraphQL */).

    • pluckConfig.globalGqlIdentifierName - Overrides the name of the default GraphQL name identifier.

  • skipDocumentsValidation - Allows to configure how to validate documents

    • skipDocumentsValidation.skipValidationAgainstSchema - A flag to disable the validation against the schema

    • skipDocumentsValidation.ignoreRules - An array of rule names to ignore during the validation. You can find a list of the available rules here.

    • skipDocumentsValidation.skipDuplicateValidation - A flag to disable the validation for duplicate documents

 

 

Environment Variables

You can use environment variables in your codegen.yml file:

schema: ${SCHEMA_PATH}
documents: ./src/**/*.graphql
generates:
  ./src/types.ts:
    plugins:
      - typescript
      - typescript-operations

You can load a .env file by adding the -r dotenv/config option to your CLI command and adding dotenv as a dependency on your project.

You can specify a default value in case an environment variable is missing:

schema: ${SCHEMA_PATH:schema.graphql}

 

 

CLI Flags

The Codegen also supports several CLI flags that allow you to override the default behavior specified in your .yml config file:

  • --config (-c) - Specifies the codegen config file to use.

  • --watch (-w) - Overrides the watch config to true. You can also specify a glob expression to create a custom watch list.

  • --silent (-s) - Overrides the silent config to true.

  • --errors-only (-e) - Overrides the errorsOnly config to true.

  • --require (-r) - Specifies require.extensions before loading the .yml file.

  • --overwrite (-o) - Overrides the overwrite config to true.

  • --profile - Use the profiler to measure performance. (see "Profiler" in "Advanced Usage")

 

 

Debug Mode

You can set the DEBUG environment variable to 1 to print debug information.

You can set the VERBOSE environment variable to 1 to print more information regarding the CLI output (listr).

 

 

Other ways to provide configuration

GraphQL-Codegen is uses cosmiconfig library to manage configuration loading.

That means you can use codegen.yml, codegen.json, or codegen.js as configuration files. You can also specify the entire configuration under a key called "codegen" in your package.json.

For more information, please refer to cosmiconfig documentation.

GraphQL-Codegen is also integrable with GraphQL-Config, so you can specify .graphqlrc as your configuration file.