Search…
Technical overview
Repository
Apps
Libs
Reference
Auto Generated Schemas
We ignore all the auto-generated files from the repository to avoid noises, make reviews easier on PRs, and only notifies teams with code reviews when needed.
You will need
java installed on your machine to be able to run the yarn schemas command, more precisely the openapi-generator sub-command. Find more about the installation here.Understanding how automatic schemas works
We are only tracking file that are coming from an external source, e.g.
contentfulTypes.d.ts that depends on contentful to be generated. The same goes for an openapi.yaml file that comes from an external service.When you do
yarn install the scripts will generate all the schemas and types for the project. It takes around ~45sec to generate all schemas, definitions types and open api schemas. The output is cached using NX to avoid re-generating all files again when no changes have been detected. It can go down up to ~5sec to run again.On the GitHub workflow, we are caching theses generated files to avoid to re-generate them at each push. However, theses files have to be updated when some specific files are changed (e.g.
*.resolvers.ts, *.dto.ts, etc).We defined a hashFiles variable in the GitHub workflow that contains the list of the files patterns that can trigger the schema script. If you follow this naming convention, your files will trigger the script once a change is detected on GitHub.
1
scripts/schemas.js
2
libs/cms/src/lib/generated/contentfulTypes.d.ts
3
apps/air-discount-scheme/web/i18n/withLocale.tsx
4
apps/air-discount-scheme/web/components/AppLayout/AppLayout.tsx
5
apps/air-discount-scheme/web/components/Header/Header.tsx
6
apps/air-discount-scheme/web/screens/**.tsx
7
apps/**/codegen.yml
8
libs/**/codegen.yml
9
apps/**/*.model.ts
10
libs/**/*.model.ts
11
apps/**/*.enum.ts
12
libs/**/*.enum.ts
13
apps/**/queries/**/*.tsx?
14
libs/**/queries/**/*.tsx?
15
apps/**/*.resolver.ts
16
libs/**/*.resolver.ts
17
apps/**/*.service.ts
18
libs/**/*.service.ts
19
apps/**/*.dto.ts
20
libs/**/*.dto.ts
21
apps/**/*.input.ts
22
libs/**/*.input.ts
23
apps/**/*.module.ts
24
libs/**/*.module.ts
25
apps/**/*.controller.ts
26
libs/**/*.controller.ts
Copied!
Adding a new script for your project
We have 4 different types of scripts that can be added inside
workspace.json to generate schemas and types.schemas/build-openapischemas/openapi-generatorschemas/build-graphql-schemaschemas/codegen
Follow the next steps to configure your project:
Openapi (schemas/build-openapi)
First, we need to create an
openApi.ts file to define the document builder. Add this file at the root of the project along the index.ts.1
import { DocumentBuilder } from '@nestjs/swagger'
2
3
export const openApi = new DocumentBuilder()
4
.setTitle('title')
5
.setDescription('description')
6
.setVersion('version')
7
.addTag('application')
8
.build()
Copied!
Next, we need to create an
buildOpenApi.ts that will consume the previous file and generate the openapi.yaml file.1
import { buildOpenApi } from '@island.is/infra-nest-server'
2
3
import { AppModule } from './app/app.module'
4
import { openApi } from './openApi'
5
6
buildOpenApi({
7
path: 'PATH/openapi.yaml',
8
appModule: AppModule,
9
openApi,
10
})
Copied!
Finally, we add the script into
workspace.json for the project.1
"schemas/build-openapi": {
2
"builder": "@nrwl/workspace:run-commands",
3
"options": {
4
"outputPath": "PATH/openapi.yaml",
5
"command": "yarn ts-node -P PATH/tsconfig.app.json PATH/buildOpenApi.ts"
6
}
7
}
Copied!
If your service is running a service like redis, you will need to ignore it for running the build-open-api script like follow in the
workspace.json1
"command": "cross-env INIT_SCHEMA=true yarn ts-node ..."
Copied!
and in the module where the redis manager is defined
1
if (process.env.INIT_SCHEMA === 'true') {
2
CacheModule = NestCacheModule.register()
3
} else {
4
CacheModule = NestCacheModule.register({
5
store: redisStore,
6
redisInstance: createNestJSCache({...}),
7
})
8
}
Copied!
Typed fetch client (schemas/openapi-generator)
We will now use the
openapi.yaml file generated from the previous script to run openapi-generator.If the
.yaml file comes from an outside source, don't name it openapi.yaml, otherwise it will be git ignored.Add the following script to the
workspace.json's project.1
"schemas/openapi-generator": {
2
"builder": "@nrwl/workspace:run-commands",
3
"options": {
4
"outputPath": "PATH/gen/fetch",
5
"command": "yarn openapi-generator -o PATH/gen/fetch -i PATH/openapi.yaml"
6
}
7
}
Copied!
Graphql (schemas/build-graphql-schema)
If you are creating an API, you'll need to hook up the
build-graphql-schema script in workspace.json so the CI can create the GraphQL schema in the pipeline without starting running the server:1
"schemas/build-graphql-schema": {
2
"builder": "@nrwl/workspace:run-commands",
3
"options": {
4
"command": "yarn ts-node -P PATH/tsconfig.json PATH_TO_ROOT_MODULE"
5
}
6
}
Copied!
Client (schemas/codegen)
The last kind is the client-side consuming an
api.graphql file.Create an
codegen.yml file in your project1
schema:
2
- PATH/api.graphql
3
generates:
4
PATH/schema.d.ts:
5
plugins:
6
- ...
7
hooks:
8
afterAllFileWrite:
9
- prettier --write
Copied!
Finally, you need to add it inside your
workspace.json1
"schemas/codegen": {
2
"builder": "@nrwl/workspace:run-commands",
3
"options": {
4
"command": "graphql-codegen --config PATH/codegen.yml"
5
}
6
}
Copied!
You should use one of the following names for the generated file from the codegen.yml configuration:
schema.d.ts, schema.tsx, schema.ts, possibleTypes.json, fragmentTypes.json to be ignored from git.Generating schema and client types
If you are changing your openapi service, you might need to generate the files again using:
1
yarn nx run <project>:schemas/build-openapi
Copied!
And generate the types fetch client with:
1
yarn nx run <project>:schemas/openapi-generator
Copied!
All API calls should be type checked to backend schemas. When you update an API, you may need to generate schema files:
1
yarn nx run <project>:schemas/build-graphql-schema
Copied!
And generate client types that depend on the schema:
1
yarn nx run <project>:schemas/codegen
Copied!
Last modified 22d ago