diff --git a/website/src/pages/docs/custom-codegen/_meta.json b/website/src/pages/docs/custom-codegen/_meta.json index dce618ba955..9a93ef04b6f 100644 --- a/website/src/pages/docs/custom-codegen/_meta.json +++ b/website/src/pages/docs/custom-codegen/_meta.json @@ -4,5 +4,6 @@ "validate-configuration": "Validate Configuration", "extend-schema": "Extend Schema", "using-visitor": "Using Visitor Pattern", + "document-transform": "Document Transform", "contributing": "Contributing" } diff --git a/website/src/pages/docs/custom-codegen/document-transform.mdx b/website/src/pages/docs/custom-codegen/document-transform.mdx new file mode 100644 index 00000000000..b316d0c1c75 --- /dev/null +++ b/website/src/pages/docs/custom-codegen/document-transform.mdx @@ -0,0 +1,117 @@ +import { Callout } from '@theguild/components' + +# Document Transform + +## Basic Usage + +Each plugin can also provide a function `transformDocuments` for transforming `documents`: + +```js {5-14} +const { visit } = require('graphql') + +module.exports = { + plugin() {}, // Nothing to do + transformDocuments(schema, documents, config) { + return documents.map(documentFile => { + documentFile.document = visit(documentFile.document, { + Field(node) { + // This function triggered per each field + } + }) + return documentFile + }) + } +} +``` + +You can specify the plugin with `documentTransforms` field in your config: + +```ts {9} +import { CodegenConfig } from '@graphql-codegen/cli' + +const config: CodegenConfig = { + schema: 'http://localhost:4000/graphql', + documents: ['src/**/*.tsx'], + generates: { + './src/gql/': { + preset: 'client', + documentTransforms: ['./my-transform.js'], + plugins: [] + } + } +} + +export default config +``` + + + If you specify it with only the `plugins` field and not with the `documentTransforms` field, the `transformDocuments` + function will not be executed. + + +## Example + +For example, let's remove a `@loacalOnlyDirective` directive from documents: + +```js +const { visit, print } = require('graphql') + +module.exports = { + plugin(schema, documents, config) { + // Output `documents` as an example. + return documents.map(documentFile => `${print(documentFile.document)}`).join('\n') + }, + transformDocuments(schema, documents, config) { + return documents.map(documentFile => { + documentFile.document = visit(documentFile.document, { + Directive: { + leave(node) { + if (node.name.value === 'localOnlyDirective') return null + } + } + }) + return documentFile + }) + } +} +``` + +If you want to execute the `plugin` function as above, you specify it with the `plugins` field as well as the `documentTransforms` field in your config: + +```ts {9-10} +import { CodegenConfig } from '@graphql-codegen/cli' + +const config: CodegenConfig = { + schema: 'http://localhost:4000/graphql', + documents: ['src/**/*.tsx'], + generates: { + './src/gql/': { + preset: 'client', + documentTransforms: ['./my-transform.js'], + plugins: ['./my-transform.js'] + } + } +} + +export default config +``` + +## Validation + +Plugin can also validate before executing the `transformDocuments`: + +```js {20-24} +const { visit } = require('graphql') + +module.exports = { + plugin() {}, + transformDocuments(schema, documents, config) { + return documents + }, + validateBeforeTransformDocuments(schema, documents, config) { + if (config.somethingWrong) { + throw new Error(`Something wrong!`) + } + } +} +```