NX tooling dev/style guide

Generators

Generators live in the tools/workspace-plugin/src/generators folder. Learn more about Nx generators.

Scaffolding

<generator-name>/
|- files/
    |- some-file.ts__tmpl__
    |- config.json__tmpl__
|- lib/
    |- utils.ts
    |- utils.spec.ts
    |- add-foo.ts
    |- add-foo.spec.ts
|- index.ts
|- index.spec.ts
|- schema.ts
|- schema.json
|- README.md

files/ (optional)

Place for static or dynamic templates used to generate files.

⚠️ Make sure every file ends with __tmpl__ suffix. This suffix should be part of the extension, not a separate extension.

• ✅ my-file.ts__tmpl__
• ❌ my-file.ts.__tmpl__ (notice the extra .)

The __tmpl__ suffix will be removed as part of the generation.

lib/ (optional)

Consider splitting your logic into smaller modules if your generator becomes too big/complicated. This is the place where you should split your logic into smaller modules.

If it makes sense, try to provide a unit test for every module.

index.ts

Entry point to the generator.

index.spec.ts

Integration tests for the generator as a whole.

schema.ts

TypeScript interface that matches schema.json. You can generate this from the json file by running:

• npx json-schema-to-typescript@latest -i tools/workspace-plugin/src/generators/<name>/schema.json -o tools/workspace-plugin/src/generators/<name>/schema.d.ts --additionalProperties false

schema.json

Provides a description of the generator, available options, validation information, and default values. This is processed by nx cli when invoking generator to provide argument validations/processing/prompts.

README.md

Generator documentation - about + API

Run following to update TOC:

npx markdown-toc --bullets "-"  -i tools/generators/<generator-name>/README.md

ℹ️ NOTE: In future, this will be automatically generated.

Bootstrap new generator

CLI:

yarn nx g @fluentui/workspace-plugin:workspace-generator

Nx Console:

Migrations

Migrations live in the tools/generators folder. They should ideally live in tools/migrations but due to how workspace generator invocations works in nx, we are restricted to place them alongside standard generators.

Migrations follow same rules as Generators as they behave the same but serve a different purpose.

⚠️ Migrations generator's name should start with migrate-*.

• ✅ migrate-my-package
• ❌ migration-mu-package

Executors

Executors live in the tools/workspace-plugin/src/executors folder. Learn more about Nx executors.

Scaffolding

schema.d.ts

TypeScript interface that matches schema.json. You can generate this from the json file by running:

• npx json-schema-to-typescript@latest -i tools/workspace-plugin/src/executors/<name>/schema.json -o tools/workspace-plugin/src/executors/<name>/schema.d.ts --additionalProperties false

schema.json

Provides a description of the generator, available options, validation information, and default values. This is processed by nx cli when invoking generator to provide argument validations/processing/prompts.

Bootstrap new executor

yarn nx g @nx/plugin:executor --directory tools/workspace-plugin/src/executors/<name-of-executor>