Add document-transform.mdx

Author: kazekyo

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"
 }

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
+```
+
+<Callout>
+  If you specify it with only the `plugins` field and not with the `documentTransforms` field, the `transformDocuments`
+  function will not be executed.
+</Callout>
+
+## 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!`)
+    }
+  }
+}
+```