From 842e6cf8ff8ff4b39c753adbcc1eb3b43b244a87 Mon Sep 17 00:00:00 2001 From: AgentEnder Date: Mon, 23 Oct 2023 16:08:27 -0400 Subject: [PATCH] docs(core): update documentation for nx plugin options --- .../recipes/plugins/project-graph-plugins.md | 59 ++++++++++++++++++- docs/shared/reference/nx-json.md | 22 +++++++ 2 files changed, 78 insertions(+), 3 deletions(-) diff --git a/docs/shared/recipes/plugins/project-graph-plugins.md b/docs/shared/recipes/plugins/project-graph-plugins.md index 2e6634e0107568..2f229492187ef5 100644 --- a/docs/shared/recipes/plugins/project-graph-plugins.md +++ b/docs/shared/recipes/plugins/project-graph-plugins.md @@ -58,7 +58,7 @@ A simplified version of Nx's built-in `project.json` plugin is shown below, whic ```typescript {% fileName="/my-plugin/index.ts" %} export const createNodes: CreateNodes = [ '**/project.json', - (projectConfigurationFile: string, context: CreateNodesContext) => { + (projectConfigurationFile: string, opts, context: CreateNodesContext) => { const projectConfiguration = readJson(projectConfigurationFile); const projectRoot = dirname(projectConfigurationFile); const projectName = projectConfiguration.name; @@ -97,7 +97,8 @@ It's more common for plugins to create new dependencies. First-party code contai The shape of the [`createDependencies`](/nx-api/devkit/documents/CreateDependencies) function follows: ```typescript -export type CreateDependencies = ( +export type CreateDependencies = ( + opts: T, context: CreateDependenciesContext ) => CandidateDependency[] | Promise; ``` @@ -166,7 +167,7 @@ Even though the plugin is written in JavaScript, resolving dependencies of diffe A small plugin that recognizes dependencies to projects in the current workspace which a referenced in another project's `package.json` file may look like so: ```typescript {% fileName="/my-plugin/index.ts" %} -export const createNodes: CreateNodes = (ctx) => { +export const createDependencies: CreateDependencies = (opts, ctx) => { const packageJsonProjectMap = new Map(); const nxProjects = Object.values(ctx.projectsConfigurations); const results = []; @@ -211,6 +212,54 @@ Breaking down this example, we can see that it follows this flow: 7. Pushes it into the located dependency array 8. Returns the located dependencies +## Accepting Plugin Options + +When looking at `createNodes`, and `createDependencies` you may notice a parameter called `options`. This is the first parameter for `createDependencies` or the second parameter for `createDependencies`. + +By default, its typed as unknown. This is because it belongs to the plugin author. The `CreateNodes`, `CreateDependencies`, and `NxPluginV2` types all accept a generic parameter that allows you to specify the type of the options. + +The options are read from `nx.json` when your plugin is specified as an object rather than just its module name. + +As an example, the below `nx.json` file specifies a plugin called `my-plugin` and passes it an option called `tagName`. + +```json +{ + "plugins": [ + { + "name": "my-plugin", + "options": { + "tagName": "plugin:my-plugin" + } + } + ] +} +``` + +`my-plugin` could then consume these options to add a tag to each project it detected: + +```typescript +type MyPluginOptions = { tagName: string }; + +export const createNodes: CreateNodes = [ + '**/project.json', + (fileName, opts, ctx) => { + const root = dirname(fileName); + const name = basename(fileName); + + return { + projects: { + [name]: { + root, + tags: opts.tagName ? [opts.tagName] : [], + }, + }, + }; + }, +]; +``` + +This functionality is available in Nx 17 or higher. + ## Visualizing the Project Graph You can then visualize the project graph as described [here](/core-features/explore-graph). However, there is a cache that Nx uses to avoid recalculating the project graph as much as possible. As you develop your project graph plugin, it might be a good idea to set the following environment variable to disable the project graph cache: `NX_CACHE_PROJECT_GRAPH=false`. @@ -223,3 +272,7 @@ It might also be a good idea to ensure that the dep graph is not running on the The [nrwl/nx-go-project-graph-plugin](https://github.com/nrwl/nx-go-project-graph-plugin) repo contains an example project graph plugin which adds [Go](https://golang.org/) dependencies to the Nx Project Graph! A similar approach can be used for other languages. {% github-repository url="https://github.com/nrwl/nx-go-project-graph-plugin" /%} --> + +``` + +``` diff --git a/docs/shared/reference/nx-json.md b/docs/shared/reference/nx-json.md index 8a0162906e7fdf..bbd2362d78e722 100644 --- a/docs/shared/reference/nx-json.md +++ b/docs/shared/reference/nx-json.md @@ -237,6 +237,28 @@ If you are using distributed task execution and disable caching for a given targ {% /callout %} +### Plugins + +Nx plugins can provide generators, executors, as well as modifying the project graph. Any plugin that modifies the project graph must be listed in the `plugins` array in `nx.json`. Plugins which modify the project graph generally either add nodes or dependencies to the graph. + +This can be read about in more detail in the [plugins guide](/extending-nx/recipes/project-graph-plugins). + +Inside `nx.json`, these plugins are either listed by their module path, or an object that references the plugin's module path and options that should be passed to it. + +```json {% fileName="nx.json" %} +{ + "plugins": [ + "@my-org/graph-plugin", + { + "plugin": "@my-org/other-plugin", + "options": { + "someOption": true + } + } + ] +} +``` + ### Generators Default generator options are configured in `nx.json` as well. For instance, the following tells Nx to always