Sync Generators
In Nx 19.8, you can use sync generators to ensure that your repository is maintained in a correct state. One specific application is to use the project graph to update files. These can be global configuration files or scripts, or at the task level to ensure that files are in sync before a task is run.
Sync Generator Examples:
- Update a custom CI script with binning strategies based on the current project graph
- Update TypeScript config files with project references based on the current project graph
- Ensure code is formatted in a specific way before CI is run
Task Sync Generators
Sync generators can be associated with a particular task. Nx will use the sync generator to ensure that code is correctly configured before running the task. Nx does this in different ways, depending on whether the task is being run on a developer machine or in CI.
On a developer machine, the sync generator is run in --dry-run mode and if files would be changed by the generator, the user is prompted to run the generator or skip it. This prompt can be disabled by setting the sync.applyChanges property to true or false in the nx.json file.
1{
2 "$schema": "packages/nx/schemas/nx-schema.json",
3 ...
4 "sync": {
5 "applyChanges": true
6 }
7}
8If you set sync.applyChanges to false, then developers must run nx sync manually before pushing changes. Otherwise, CI may fail due to the workspace being out of sync.
In CI, the sync generator is run in --dry-run mode and if files would be changed by the generator, the task fails with an error provided by the sync generator. The sync generator can be skipped in CI by passing the --skip-sync flag when executing the task, or you can skip an individual sync generator by adding that generator to the sync.disabledTaskSyncGenerators in nx.json.
1{
2 "$schema": "packages/nx/schemas/nx-schema.json",
3 ...
4 "sync": {
5 "disabledTaskSyncGenerators": ["@nx/js:typescript-sync"]
6 }
7}
8
9Use the project details view to find registered sync generators for a given task.
❯
nx show project <name>
The above command opens up the project details view, and the registered sync generators are under the Sync Generators for each target. Most sync generators are inferred when using an inference plugin. For example, the @nx/js/typescript plugin registers the @nx/js:typescript-sync generator on build and typecheck targets.
foo
Root: packages/foo
Type:library
Targets
build
tsc --build tsconfig.lib.json --pretty --verbose
Cacheable
Task sync generators can be thought of like the dependsOn property, but for generators instead of task dependencies.
To register a generator as a sync generator for a particular task, add the generator to the syncGenerators property of the task configuration.
Global Sync Generators
Global sync generators are not associated with a particular task and are executed only when the nx sync or nx sync:check command is explicitly run. They are registered in the nx.json file with the sync.globalGenerators property.
Sync the Project Graph and the File System
Nx processes the file system in order to create the project graph which is used to run tasks in the correct order and determine project dependencies. Sync generators allow you to also go the other direction and use the project graph to update the file system.
1└─ myorg
2 ├─ apps
3 │ ├─ app1
4 │ └─ app1
5 ├─ libs
6 │ └─ lib
7 ├─ nx.json
8 └─ package.json
9The ability to update the file system from the project graph makes it possible to use the Nx project graph to change the behavior of other tools that are not part of the Nx ecosystem.
Run nx sync:check in CI
Task sync generators are executed whenever their task is run, but global sync generators need to be triggered manually with nx sync. In order to effectively use sync generators, make sure to add nx sync:check to the beginning of your CI scripts so that CI can fail quickly if the code is out of sync. It is also helpful to run nx sync in a pre-commit or pre-push Git hook to encourage developers to commit code that is already in sync.