Installing GraphQL Code Generator
Overview
As mentioned in previous sections, GraphQL is strongly typed and allows introspection. GraphQL Code Generator uses this to generate code to make developers lives easier. Another excellent feature of GraphQL Code Generator is that because it generates code against the GraphQL schema, any query mistakes will throw an error at the codegen step meaning you can find errors before runtime.
GraphQL Code Generator is not limited to Typescript or React and has support for a large number of different languages and tools. We would highly recommend you check the live example for your language / setup or find another similar tool.
Installing dependencies
First we must install the required dependencies using NPM. GraphQL Code Generator uses a plugin system so we will need to both install @graphql-codegen/cli and the plugins we need. For this example the plugins we need are @graphql-codegen/typescript, @graphql-codegen/typescript-operations and @graphql-codegen/typescript-react-apollo. A full list of plugins can be found here. Finally as we only need this during development will install everything as dev dependencies using the D flag. This should look like:
npm i -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typescript-react-apollo
We advise that you look through the other plugins available here
Add codegen config file
Before the codegen can do its thing, we first need to tell it several things:
- The GraphQL endpoint
- The codegen output file
- The file / files we want to be used to generate code
- The plugins (and their settings) that we want to use
All of this is fairly simple and goes in a .ts file called codegen.ts. Full detail on all the basic configuration can be found here, and config for each plugin can be found in that plugins documentation page here. For this tutorial we will create and setup our codegen.ts file in the base folder as shown:
import { CodegenConfig } from '@graphql-codegen/cli'
const config: CodegenConfig = {
schema: 'https://s5.sanctuaryhealth.io/graphql',
documents: ['src/gql/**/*.ts'],
generates: {
'./src/gql.tsx': {
plugins: ['typescript','typescript-operations','typescript-react-apollo']
}
},
config: {
defaultScalarType: 'unknown',
scalars: {
DateTime: 'string'
},
}
}
export default config
These settings will generate code from any file with a .ts extension found in the ./src/gql folder (line 5) and place the output in ./src/gql.tsx (line 7). You will also notice we have pointed the schema at the Sanctuary Health API URL (line 4), specified the plugins we want to use (line 8) and configured our plugin settings (line 11 to line 15).
We advise you look through the possible settings so you can customize your generated code to fit your needs
Add gen command
Now that we have everything installed and our codegen config file, we need to add a command in our package.json file to run the codegen. So far our package.json file should look like this (all installed packages so far have been highlighted):
{
"name": "react-example",
"version": "0.1.0",
"private": true,
"dependencies": {
"@apollo/client": "^3.7.3",
"@testing-library/jest-dom": "^5.16.5",
"@testing-library/react": "^13.4.0",
"@testing-library/user-event": "^13.5.0",
"@types/jest": "^27.5.2",
"@types/node": "^16.18.11",
"@types/react": "^18.0.26",
"@types/react-dom": "^18.0.10",
"graphql": "^16.6.0",
"react": "^18.2.0",
"react-dom": "^18.2.0",
"react-scripts": "5.0.1",
"typescript": "^4.9.4",
"web-vitals": "^2.1.4"
},
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
},
"eslintConfig": {
"extends": [
"react-app",
"react-app/jest"
]
},
"browserslist": {
"production": [
">0.2%",
"not dead",
"not op_mini all"
],
"development": [
"last 1 chrome version",
"last 1 firefox version",
"last 1 safari version"
]
},
"devDependencies": {
"@graphql-codegen/cli": "^2.16.3",
"@graphql-codegen/typescript": "^2.8.7",
"@graphql-codegen/typescript-operations": "^2.5.12",
"@graphql-codegen/typescript-react-apollo": "^3.3.7"
}
}
To generate our file we simply need to add a new command in the scripts section. We will call this command gen and it needs to run the codegen with us providing our config file graphql-codegen -c codegen.ts. Later we should be able to run this command by typing npm run gen. Your package.json file should now look like this:
{
"name": "react-example",
"version": "0.1.0",
"private": true,
"dependencies": {
"@apollo/client": "^3.7.3",
"@testing-library/jest-dom": "^5.16.5",
"@testing-library/react": "^13.4.0",
"@testing-library/user-event": "^13.5.0",
"@types/jest": "^27.5.2",
"@types/node": "^16.18.11",
"@types/react": "^18.0.26",
"@types/react-dom": "^18.0.10",
"graphql": "^16.6.0",
"react": "^18.2.0",
"react-dom": "^18.2.0",
"react-scripts": "5.0.1",
"typescript": "^4.9.4",
"web-vitals": "^2.1.4"
},
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject",
"gen": "graphql-codegen -c codegen.ts"
},
"eslintConfig": {
"extends": [
"react-app",
"react-app/jest"
]
},
"browserslist": {
"production": [
">0.2%",
"not dead",
"not op_mini all"
],
"development": [
"last 1 chrome version",
"last 1 firefox version",
"last 1 safari version"
]
},
"devDependencies": {
"@graphql-codegen/cli": "^2.16.3",
"@graphql-codegen/typescript": "^2.8.7",
"@graphql-codegen/typescript-operations": "^2.5.12",
"@graphql-codegen/typescript-react-apollo": "^3.3.7"
}
}
If you try running npm run gen at this time it will fail as we have not added any code to generate from, we will handle this in the next section