diff --git a/docs/shared/features/generate-code.md b/docs/shared/features/generate-code.md index b66a44e6a1..e7c5ade9a8 100644 --- a/docs/shared/features/generate-code.md +++ b/docs/shared/features/generate-code.md @@ -1,36 +1,67 @@ # Generate Code -Generators provide a way to automate many tasks you regularly perform as part of your development workflow. Whether it is scaffolding out components, features, ensuring libraries are generated and structured in a certain way, or updating your configuration files, generators help you standardize these tasks in a consistent, and predictable manner. +Code generators are like automation scripts designed to streamline your workflow. Essentially, they are TypeScript functions that accept parameters and help boost your productivity by: -## Types of Generators +- Allowing you to **scaffold new projects** or **augment existing projects** with new features, like [adding Storybook support](/nx-api/storybook#generating-storybook-configuration) +- **Automating repetitive tasks** in your development workflow +- Ensuring your **code is consistent and follows best practices** -There are three main types of generators: +## Invoke Generators -1. **Plugin Generators** are available when an Nx plugin has been installed in your workspace. -2. **Local Generators** are generators that you can create for your own workspace. [Local generators](/extending-nx/recipes/local-generators) allow you to codify the processes that are unique to your own organization. -3. **Update Generators** are invoked by Nx plugins when you [update Nx](/recipes/adopting-nx) to keep your config files in sync with the latest versions of third party tools. +Generators come as part of [Nx plugins](/concepts/nx-plugins) and can be invoked using the `nx generate` command (or `nx g`) using the following syntax: `nx g : [options]`. -## Invoking Plugin Generators - -Generators allow you to create or modify your codebase in a simple and repeatable way. Generators are invoked using the [`nx generate`](/nx-api/nx/documents/generate) command. +Here's an example of generating a React library: ```shell -nx generate [plugin]:[generator-name] [options] -nx generate @nx/react:component mycmp --project=myapp +nx g @nx/react:lib mylib --directory=packages/mylib ``` -It is important to have a clean git working directory before invoking a generator so that you can easily revert changes and re-invoke the generator with different inputs. +You can also specify just the generator name and Nx will prompt you to pick between the installed plugins that provide a generator with that name. -## Build your own Generator +```shell +nx g lib mylib --directory=packages/mylib +``` -Nx comes with a Devkit that allows you to build your own generator for your Nx workspace. Learn more about it on [our docs page](/extending-nx/recipes/local-generators) or have a look at the video below: +When running this command, you could be prompted to choose between the `@nx/react` and `@nx/js` plugins that each provide a library generator. -{% youtube -src="https://www.youtube.com/embed/myqfGDWC2go" -title="Scaffold new Pkgs in a PNPM Workspaces Monorepo" -caption="Demoes how to use Nx generators in a PNPM workspace to automate the creation of libraries" -/%} +To see a list of available generators in a given plugin, run `nx list `. As an example, to list all generators in the @nx/react plugin: -## See Also +```shell +nx list @nx/react +``` -- [nx.json generator defaults](/reference/nx-json#generators) +### Use Nx Console + +If you prefer a visual interface, then [Nx Console](/getting-started/editor-setup) is an excellent alternative. It provides a way to visually find and run generators: + +![Using Nx Console to run generators](/shared/images/nx-console/nx-console-gen-code.avif) + +Nx Console is an IDE extension that can be [installed here](/getting-started/editor-setup). + +## Build Your Own Generator + +You can also customize existing generators by overwriting their behavior or create completely new ones. This is a powerful mechanism as it allows you to: + +- **automate** your organization's specific processes and workflows +- **standardize** how and where projects are created in your workspace to make sure they reflect your organization's best practices and coding standards +- **ensure** that your codebase follows your organization's best practices and style guides + +At their core, generators are just functions with a specific signature and input options that get invoked by Nx. Something like the following: + +```typescript +import { Tree, formatFiles, installPackagesTask } from '@nx/devkit'; + +export default async function (tree: Tree, schema: any) { + // Your implementation here + // ... + + await formatFiles(tree); + return () => { + installPackagesTask(tree); + }; +} +``` + +To help build generators, Nx provides the `@nx/devkit` package containing utilities and helpers. Learn more about creating your own generators on [our docs page](/extending-nx/recipes/local-generators) or watch the video below: + +{% youtube src="https://www.youtube.com/embed/myqfGDWC2go" title="Scaffold new Pkgs in a PNPM Workspaces Monorepo" caption="Demonstrates how to use Nx generators in a PNPM workspace to automate the creation of libraries" /%} diff --git a/docs/shared/images/nx-console/nx-console-gen-code.avif b/docs/shared/images/nx-console/nx-console-gen-code.avif new file mode 100644 index 0000000000..6643f03b33 Binary files /dev/null and b/docs/shared/images/nx-console/nx-console-gen-code.avif differ