docs(core): restructure plugin docs (#14349)
This commit is contained in:
Isaac Mann
GitHub
parent
415d1c745c
commit
b96a178011
@ -2210,9 +2210,25 @@
|
||||
"isExternal": false,
|
||||
"children": [
|
||||
{
|
||||
"name": "Project Inference Plugins",
|
||||
"path": "/recipes/advanced-plugins/project-inference-plugins",
|
||||
"id": "project-inference-plugins",
|
||||
"name": "Share Your Plugin",
|
||||
"path": "/recipes/advanced-plugins/share-your-plugin",
|
||||
"id": "share-your-plugin",
|
||||
"isExternal": false,
|
||||
"children": [],
|
||||
"disableCollapsible": false
|
||||
},
|
||||
{
|
||||
"name": "Create a Preset",
|
||||
"path": "/recipes/advanced-plugins/create-preset",
|
||||
"id": "create-preset",
|
||||
"isExternal": false,
|
||||
"children": [],
|
||||
"disableCollapsible": false
|
||||
},
|
||||
{
|
||||
"name": "Migration Generators",
|
||||
"path": "/recipes/advanced-plugins/migration-generators",
|
||||
"id": "migration-generators",
|
||||
"isExternal": false,
|
||||
"children": [],
|
||||
"disableCollapsible": false
|
||||
@ -2224,14 +2240,38 @@
|
||||
"isExternal": false,
|
||||
"children": [],
|
||||
"disableCollapsible": false
|
||||
},
|
||||
{
|
||||
"name": "Project Inference Plugins",
|
||||
"path": "/recipes/advanced-plugins/project-inference-plugins",
|
||||
"id": "project-inference-plugins",
|
||||
"isExternal": false,
|
||||
"children": [],
|
||||
"disableCollapsible": false
|
||||
}
|
||||
],
|
||||
"disableCollapsible": false
|
||||
},
|
||||
{
|
||||
"name": "Project Inference Plugins",
|
||||
"path": "/recipes/advanced-plugins/project-inference-plugins",
|
||||
"id": "project-inference-plugins",
|
||||
"name": "Share Your Plugin",
|
||||
"path": "/recipes/advanced-plugins/share-your-plugin",
|
||||
"id": "share-your-plugin",
|
||||
"isExternal": false,
|
||||
"children": [],
|
||||
"disableCollapsible": false
|
||||
},
|
||||
{
|
||||
"name": "Create a Preset",
|
||||
"path": "/recipes/advanced-plugins/create-preset",
|
||||
"id": "create-preset",
|
||||
"isExternal": false,
|
||||
"children": [],
|
||||
"disableCollapsible": false
|
||||
},
|
||||
{
|
||||
"name": "Migration Generators",
|
||||
"path": "/recipes/advanced-plugins/migration-generators",
|
||||
"id": "migration-generators",
|
||||
"isExternal": false,
|
||||
"children": [],
|
||||
"disableCollapsible": false
|
||||
@ -2244,6 +2284,14 @@
|
||||
"children": [],
|
||||
"disableCollapsible": false
|
||||
},
|
||||
{
|
||||
"name": "Project Inference Plugins",
|
||||
"path": "/recipes/advanced-plugins/project-inference-plugins",
|
||||
"id": "project-inference-plugins",
|
||||
"isExternal": false,
|
||||
"children": [],
|
||||
"disableCollapsible": false
|
||||
},
|
||||
{
|
||||
"name": "Environment Variables",
|
||||
"path": "/recipes/environment-variables",
|
||||
|
||||
@ -513,17 +513,17 @@
|
||||
"id": "creating-custom-executors",
|
||||
"name": "Local Executors",
|
||||
"description": "",
|
||||
"file": "shared/recipes/local-executors",
|
||||
"file": "shared/recipes/plugins/local-executors",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/executors/creating-custom-executors",
|
||||
"tags": ["use-task-executors"]
|
||||
"tags": ["use-task-executors", "create-your-own-plugin"]
|
||||
},
|
||||
{
|
||||
"id": "compose-executors",
|
||||
"name": "Compose Executors",
|
||||
"description": "",
|
||||
"file": "shared/recipes/compose-executors",
|
||||
"file": "shared/recipes/plugins/compose-executors",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/executors/compose-executors",
|
||||
@ -558,17 +558,17 @@
|
||||
"id": "creating-custom-executors",
|
||||
"name": "Local Executors",
|
||||
"description": "",
|
||||
"file": "shared/recipes/local-executors",
|
||||
"file": "shared/recipes/plugins/local-executors",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/executors/creating-custom-executors",
|
||||
"tags": ["use-task-executors"]
|
||||
"tags": ["use-task-executors", "create-your-own-plugin"]
|
||||
},
|
||||
"/recipes/executors/compose-executors": {
|
||||
"id": "compose-executors",
|
||||
"name": "Compose Executors",
|
||||
"description": "",
|
||||
"file": "shared/recipes/compose-executors",
|
||||
"file": "shared/recipes/plugins/compose-executors",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/executors/compose-executors",
|
||||
@ -584,17 +584,17 @@
|
||||
"id": "local-generators",
|
||||
"name": "Local Generators",
|
||||
"description": "",
|
||||
"file": "shared/recipes/local-generators",
|
||||
"file": "shared/recipes/generators/local-generators",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/generators/local-generators",
|
||||
"tags": ["use-code-generators"]
|
||||
"tags": ["use-code-generators", "create-your-own-plugin"]
|
||||
},
|
||||
{
|
||||
"id": "composing-generators",
|
||||
"name": "Composing Generators",
|
||||
"description": "",
|
||||
"file": "shared/generators/composing-generators",
|
||||
"file": "shared/recipes/generators/composing-generators",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/generators/composing-generators",
|
||||
@ -604,7 +604,7 @@
|
||||
"id": "generator-options",
|
||||
"name": "Generator Options",
|
||||
"description": "",
|
||||
"file": "shared/generators/generator-options",
|
||||
"file": "shared/recipes/generators/generator-options",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/generators/generator-options",
|
||||
@ -614,7 +614,7 @@
|
||||
"id": "creating-files",
|
||||
"name": "Creating Files",
|
||||
"description": "",
|
||||
"file": "shared/generators/creating-files",
|
||||
"file": "shared/recipes/generators/creating-files",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/generators/creating-files",
|
||||
@ -624,7 +624,7 @@
|
||||
"id": "modifying-files",
|
||||
"name": "Modifying Files",
|
||||
"description": "",
|
||||
"file": "shared/generators/modifying-files",
|
||||
"file": "shared/recipes/generators/modifying-files",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/generators/modifying-files",
|
||||
@ -639,17 +639,17 @@
|
||||
"id": "local-generators",
|
||||
"name": "Local Generators",
|
||||
"description": "",
|
||||
"file": "shared/recipes/local-generators",
|
||||
"file": "shared/recipes/generators/local-generators",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/generators/local-generators",
|
||||
"tags": ["use-code-generators"]
|
||||
"tags": ["use-code-generators", "create-your-own-plugin"]
|
||||
},
|
||||
"/recipes/generators/composing-generators": {
|
||||
"id": "composing-generators",
|
||||
"name": "Composing Generators",
|
||||
"description": "",
|
||||
"file": "shared/generators/composing-generators",
|
||||
"file": "shared/recipes/generators/composing-generators",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/generators/composing-generators",
|
||||
@ -659,7 +659,7 @@
|
||||
"id": "generator-options",
|
||||
"name": "Generator Options",
|
||||
"description": "",
|
||||
"file": "shared/generators/generator-options",
|
||||
"file": "shared/recipes/generators/generator-options",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/generators/generator-options",
|
||||
@ -669,7 +669,7 @@
|
||||
"id": "creating-files",
|
||||
"name": "Creating Files",
|
||||
"description": "",
|
||||
"file": "shared/generators/creating-files",
|
||||
"file": "shared/recipes/generators/creating-files",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/generators/creating-files",
|
||||
@ -679,7 +679,7 @@
|
||||
"id": "modifying-files",
|
||||
"name": "Modifying Files",
|
||||
"description": "",
|
||||
"file": "shared/generators/modifying-files",
|
||||
"file": "shared/recipes/generators/modifying-files",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/generators/modifying-files",
|
||||
@ -692,50 +692,110 @@
|
||||
"file": "",
|
||||
"itemList": [
|
||||
{
|
||||
"id": "project-inference-plugins",
|
||||
"name": "Project Inference Plugins",
|
||||
"id": "share-your-plugin",
|
||||
"name": "Share Your Plugin",
|
||||
"description": "",
|
||||
"file": "shared/extending-nx/project-inference-plugins",
|
||||
"file": "shared/recipes/plugins/share-your-plugin",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/advanced-plugins/project-inference-plugins",
|
||||
"path": "/recipes/advanced-plugins/share-your-plugin",
|
||||
"tags": ["create-your-own-plugin"]
|
||||
},
|
||||
{
|
||||
"id": "create-preset",
|
||||
"name": "Create a Preset",
|
||||
"description": "",
|
||||
"file": "shared/recipes/plugins/create-preset",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/advanced-plugins/create-preset",
|
||||
"tags": ["create-your-own-plugin"]
|
||||
},
|
||||
{
|
||||
"id": "migration-generators",
|
||||
"name": "Migration Generators",
|
||||
"description": "",
|
||||
"file": "shared/recipes/plugins/migration-generators",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/advanced-plugins/migration-generators",
|
||||
"tags": ["create-your-own-plugin"]
|
||||
},
|
||||
{
|
||||
"id": "project-graph-plugins",
|
||||
"name": "Project Graph Plugins",
|
||||
"description": "",
|
||||
"file": "shared/extending-nx/project-graph-plugins",
|
||||
"file": "shared/recipes/plugins/project-graph-plugins",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/advanced-plugins/project-graph-plugins",
|
||||
"tags": ["create-your-own-plugin", "explore-graph"]
|
||||
},
|
||||
{
|
||||
"id": "project-inference-plugins",
|
||||
"name": "Project Inference Plugins",
|
||||
"description": "",
|
||||
"file": "shared/recipes/plugins/project-inference-plugins",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/advanced-plugins/project-inference-plugins",
|
||||
"tags": ["create-your-own-plugin"]
|
||||
}
|
||||
],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/advanced-plugins",
|
||||
"tags": []
|
||||
},
|
||||
"/recipes/advanced-plugins/project-inference-plugins": {
|
||||
"id": "project-inference-plugins",
|
||||
"name": "Project Inference Plugins",
|
||||
"/recipes/advanced-plugins/share-your-plugin": {
|
||||
"id": "share-your-plugin",
|
||||
"name": "Share Your Plugin",
|
||||
"description": "",
|
||||
"file": "shared/extending-nx/project-inference-plugins",
|
||||
"file": "shared/recipes/plugins/share-your-plugin",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/advanced-plugins/project-inference-plugins",
|
||||
"path": "/recipes/advanced-plugins/share-your-plugin",
|
||||
"tags": ["create-your-own-plugin"]
|
||||
},
|
||||
"/recipes/advanced-plugins/create-preset": {
|
||||
"id": "create-preset",
|
||||
"name": "Create a Preset",
|
||||
"description": "",
|
||||
"file": "shared/recipes/plugins/create-preset",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/advanced-plugins/create-preset",
|
||||
"tags": ["create-your-own-plugin"]
|
||||
},
|
||||
"/recipes/advanced-plugins/migration-generators": {
|
||||
"id": "migration-generators",
|
||||
"name": "Migration Generators",
|
||||
"description": "",
|
||||
"file": "shared/recipes/plugins/migration-generators",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/advanced-plugins/migration-generators",
|
||||
"tags": ["create-your-own-plugin"]
|
||||
},
|
||||
"/recipes/advanced-plugins/project-graph-plugins": {
|
||||
"id": "project-graph-plugins",
|
||||
"name": "Project Graph Plugins",
|
||||
"description": "",
|
||||
"file": "shared/extending-nx/project-graph-plugins",
|
||||
"file": "shared/recipes/plugins/project-graph-plugins",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/advanced-plugins/project-graph-plugins",
|
||||
"tags": ["create-your-own-plugin", "explore-graph"]
|
||||
},
|
||||
"/recipes/advanced-plugins/project-inference-plugins": {
|
||||
"id": "project-inference-plugins",
|
||||
"name": "Project Inference Plugins",
|
||||
"description": "",
|
||||
"file": "shared/recipes/plugins/project-inference-plugins",
|
||||
"itemList": [],
|
||||
"isExternal": false,
|
||||
"path": "/recipes/advanced-plugins/project-inference-plugins",
|
||||
"tags": ["create-your-own-plugin"]
|
||||
},
|
||||
"/recipes/environment-variables": {
|
||||
"id": "environment-variables",
|
||||
"name": "Environment Variables",
|
||||
|
||||
@ -162,7 +162,7 @@
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/extending-nx/project-graph-plugins",
|
||||
"file": "shared/recipes/plugins/project-graph-plugins",
|
||||
"id": "project-graph-plugins",
|
||||
"name": "Project Graph Plugins",
|
||||
"path": "/recipes/advanced-plugins/project-graph-plugins"
|
||||
@ -466,14 +466,14 @@
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/recipes/local-executors",
|
||||
"file": "shared/recipes/plugins/local-executors",
|
||||
"id": "creating-custom-executors",
|
||||
"name": "Local Executors",
|
||||
"path": "/recipes/executors/creating-custom-executors"
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/recipes/compose-executors",
|
||||
"file": "shared/recipes/plugins/compose-executors",
|
||||
"id": "compose-executors",
|
||||
"name": "Compose Executors",
|
||||
"path": "/recipes/executors/compose-executors"
|
||||
@ -559,35 +559,35 @@
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/recipes/local-generators",
|
||||
"file": "shared/recipes/generators/local-generators",
|
||||
"id": "local-generators",
|
||||
"name": "Local Generators",
|
||||
"path": "/recipes/generators/local-generators"
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/generators/composing-generators",
|
||||
"file": "shared/recipes/generators/composing-generators",
|
||||
"id": "composing-generators",
|
||||
"name": "Composing Generators",
|
||||
"path": "/recipes/generators/composing-generators"
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/generators/generator-options",
|
||||
"file": "shared/recipes/generators/generator-options",
|
||||
"id": "generator-options",
|
||||
"name": "Generator Options",
|
||||
"path": "/recipes/generators/generator-options"
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/generators/creating-files",
|
||||
"file": "shared/recipes/generators/creating-files",
|
||||
"id": "creating-files",
|
||||
"name": "Creating Files",
|
||||
"path": "/recipes/generators/creating-files"
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/generators/modifying-files",
|
||||
"file": "shared/recipes/generators/modifying-files",
|
||||
"id": "modifying-files",
|
||||
"name": "Modifying Files",
|
||||
"path": "/recipes/generators/modifying-files"
|
||||
@ -624,17 +624,52 @@
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/extending-nx/project-inference-plugins",
|
||||
"id": "project-inference-plugins",
|
||||
"name": "Project Inference Plugins",
|
||||
"path": "/recipes/advanced-plugins/project-inference-plugins"
|
||||
"file": "shared/recipes/plugins/local-executors",
|
||||
"id": "creating-custom-executors",
|
||||
"name": "Local Executors",
|
||||
"path": "/recipes/executors/creating-custom-executors"
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/extending-nx/project-graph-plugins",
|
||||
"file": "shared/recipes/generators/local-generators",
|
||||
"id": "local-generators",
|
||||
"name": "Local Generators",
|
||||
"path": "/recipes/generators/local-generators"
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/recipes/plugins/share-your-plugin",
|
||||
"id": "share-your-plugin",
|
||||
"name": "Share Your Plugin",
|
||||
"path": "/recipes/advanced-plugins/share-your-plugin"
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/recipes/plugins/create-preset",
|
||||
"id": "create-preset",
|
||||
"name": "Create a Preset",
|
||||
"path": "/recipes/advanced-plugins/create-preset"
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/recipes/plugins/migration-generators",
|
||||
"id": "migration-generators",
|
||||
"name": "Migration Generators",
|
||||
"path": "/recipes/advanced-plugins/migration-generators"
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/recipes/plugins/project-graph-plugins",
|
||||
"id": "project-graph-plugins",
|
||||
"name": "Project Graph Plugins",
|
||||
"path": "/recipes/advanced-plugins/project-graph-plugins"
|
||||
},
|
||||
{
|
||||
"description": "",
|
||||
"file": "shared/recipes/plugins/project-inference-plugins",
|
||||
"id": "project-inference-plugins",
|
||||
"name": "Project Inference Plugins",
|
||||
"path": "/recipes/advanced-plugins/project-inference-plugins"
|
||||
}
|
||||
],
|
||||
"intro": [
|
||||
|
||||
@ -1,4 +1,6 @@
|
||||
Nx plugins are npm packages that contain generators and executors to extend a Nx workspace. Generators are blueprints to create new files from templates, and executors run those files. These plugins also update the `nx.json` when generating new libs or apps.
|
||||
Nx plugins are npm packages that contain [generators](/plugin-features/use-code-generators) and [executors](/plugin-features/use-task-executors) to extend a Nx workspace.
|
||||
|
||||
At its core, a generator is a function that creates or modifies code and an executor is a function that processes code. Nx makes it easier to call those functions from the terminal or through the [Nx Console UI](/core-features/integrate-with-editors). And you can use helper utils in the [Nx Devkit](/packages/devkit) to help build your generator or executor.
|
||||
|
||||
> A list of plugins that is maintained by Nrwl is found in the [Nrwl/nx repo](https://github.com/nrwl/nx/tree/master/packages). \
|
||||
> A list of custom plugins created by the community is found in the [Community](/community) section.
|
||||
@ -21,7 +23,7 @@ npx create-nx-plugin my-org --pluginName my-plugin
|
||||
|
||||
This command creates a brand-new workspace, and sets up a pre-configured plugin with the specified name.
|
||||
|
||||
> Note, the command above will create a plugin the package name set to `@my-org/my-plugin`. You can pass `--importPath` to provide a different package name.
|
||||
> Note, the command above will create a plugin with the package name set to `@my-org/my-plugin`. You can pass `--importPath` to provide a different package name.
|
||||
|
||||
> If you do not want to create a new workspace, install the `@nrwl/nx-plugin` dependency in an already existing workspace with npm or yarn. Then run `nx g @nrwl/nx-plugin:plugin [pluginName]`.
|
||||
|
||||
@ -153,120 +155,3 @@ To make sure that assets are copied to the dist folder, open the plugin's `proje
|
||||
## Using your Nx Plugin
|
||||
|
||||
To use your plugin, simply list it in `nx.json` or use its generators and executors as you would for any other plugin. This could look like `nx g @my-org/my-plugin:lib` for generators or `"executor": "@my-org/my-plugin:build"` for executors. It should be usable in all of the same ways as published plugins in your local workspace immediately after generating it. This includes setting it up as the default collection in `nx.json`, which would allow you to run `nx g lib` and hit your plugin's generator.
|
||||
|
||||
## Publishing your Nx Plugin
|
||||
|
||||
In order to use your plugin in other workspaces or share it with the community, you will need to publish it to an npm registry. To publish your plugin follow these steps:
|
||||
|
||||
1. Build your plugin with the command `nx run my-plugin:build`
|
||||
1. `npm publish ./dist/package/my-plugin` and follow the prompts from npm.
|
||||
1. That's it!
|
||||
|
||||
{% callout type="warning" title="Version bump" %}
|
||||
Currently you will have to modify the `package.json` version by yourself or with a tool.
|
||||
{% /callout %}
|
||||
|
||||
After that, you can then install your plugin like any other npm package,
|
||||
`npm i -D @my-org/my-plugin` or `yarn add -D @my-org/my-plugin`.
|
||||
|
||||
### Listing your Nx Plugin
|
||||
|
||||
Nx provides a utility (`nx list`) that lists both core and community plugins. To submit your plugin, please follow the steps below:
|
||||
|
||||
- Fork the [Nx repo](https://github.com/nrwl/nx/fork) (if you haven't already)
|
||||
- Update the [`community/approved-plugins.json` file](https://github.com/nrwl/nx/blob/master/community/approved-plugins.json) with a new entry for your plugin that includes name, url and description
|
||||
- Use the following commit message template: `chore(core): nx plugin submission [PLUGIN_NAME]`
|
||||
- push your changes, and run `yarn submit-plugin`
|
||||
|
||||
> The `yarn submit-plugin` command automatically opens the Github pull request process with the correct template.
|
||||
|
||||
We will then verify the plugin, offer suggestions or merge the pull request!
|
||||
|
||||
## Preset
|
||||
|
||||
A Preset is a customization option which you provide when creating a new workspace. TS, Node, React are some internal presets that Nx provides by default.
|
||||
|
||||
{% youtube
|
||||
src="https://www.youtube.com/embed/yGUrF0-uqaU"
|
||||
title="Develop a Nx Preset for your Nx Plugin"
|
||||
width="100%" /%}
|
||||
|
||||
### Custom Preset
|
||||
|
||||
At its core a preset is a generator, which we can create inside of a plugin.
|
||||
If you **don't** have an existing plugin you can create one by running
|
||||
|
||||
```shell
|
||||
npx create-nx-plugin my-org --pluginName my-plugin
|
||||
```
|
||||
|
||||
To create our preset inside of our plugin we can run
|
||||
|
||||
```shell
|
||||
nx generate @nrwl/nx-plugin:generator --name=preset --project=happynrwl
|
||||
```
|
||||
|
||||
{% callout type="warning" title="Double check" %}
|
||||
The word `preset` is required for the name of this generator
|
||||
{% /callout %}
|
||||
|
||||
You should have a similar structure to this:
|
||||
|
||||
```text
|
||||
happynrwl/
|
||||
├── e2e
|
||||
├── jest.config.js
|
||||
├── jest.preset.js
|
||||
├── nx.json
|
||||
├── package-lock.json
|
||||
├── package.json
|
||||
├── packages
|
||||
│ └── happynrwl
|
||||
│ ├── src
|
||||
│ │ ├── executors
|
||||
│ │ ├── generators
|
||||
│ │ │ ├── happynrwl
|
||||
│ │ │ └── preset // <------------- Here
|
||||
│ │ └── index.ts
|
||||
├── tools
|
||||
└── tsconfig.base.json
|
||||
```
|
||||
|
||||
After the command is finished, the preset generator is created under the folder named **preset**.
|
||||
The **generator.ts** provides an entry point to the generator. This file contains a function that is called to perform manipulations on a tree that represents the file system. The **schema.json** provides a description of the generator, available options, validation information, and default values.
|
||||
|
||||
Here is the sample generator function which you can customize to meet your needs.
|
||||
|
||||
```typescript
|
||||
export default async function (tree: Tree, options: PresetGeneratorSchema) {
|
||||
const normalizedOptions = normalizeOptions(tree, options);
|
||||
addProjectConfiguration(tree, normalizedOptions.projectName, {
|
||||
root: normalizedOptions.projectRoot,
|
||||
projectType: 'application',
|
||||
sourceRoot: `${normalizedOptions.projectRoot}/src`,
|
||||
targets: {
|
||||
exec: {
|
||||
executor: 'nx:run-commands',
|
||||
options: {
|
||||
command: `node ${projectRoot}/src/index.js`,
|
||||
},
|
||||
},
|
||||
},
|
||||
tags: normalizedOptions.parsedTags,
|
||||
});
|
||||
addFiles(tree, normalizedOptions);
|
||||
await formatFiles(tree);
|
||||
}
|
||||
```
|
||||
|
||||
To get an in-depth guide on customizing/running or debugging your generator see [local generators](/recipes/generators/local-generators).
|
||||
|
||||
#### Usage
|
||||
|
||||
Before you are able to use your newly created preset you must package and publish it to a registry.
|
||||
|
||||
After you have published your plugin to a registry you can now use your preset when creating a new workspace
|
||||
|
||||
```shell
|
||||
npx create-nx-workspace my-workspace --preset=my-plugin-name
|
||||
```
|
||||
|
||||
@ -831,14 +831,14 @@
|
||||
{
|
||||
"name": "Local Executors",
|
||||
"id": "creating-custom-executors",
|
||||
"tags": ["use-task-executors"],
|
||||
"file": "shared/recipes/local-executors"
|
||||
"tags": ["use-task-executors", "create-your-own-plugin"],
|
||||
"file": "shared/recipes/plugins/local-executors"
|
||||
},
|
||||
{
|
||||
"name": "Compose Executors",
|
||||
"id": "compose-executors",
|
||||
"tags": ["use-task-executors"],
|
||||
"file": "shared/recipes/compose-executors"
|
||||
"file": "shared/recipes/plugins/compose-executors"
|
||||
}
|
||||
]
|
||||
},
|
||||
@ -850,32 +850,32 @@
|
||||
{
|
||||
"name": "Local Generators",
|
||||
"id": "local-generators",
|
||||
"tags": ["use-code-generators"],
|
||||
"file": "shared/recipes/local-generators"
|
||||
"tags": ["use-code-generators", "create-your-own-plugin"],
|
||||
"file": "shared/recipes/generators/local-generators"
|
||||
},
|
||||
{
|
||||
"name": "Composing Generators",
|
||||
"id": "composing-generators",
|
||||
"tags": ["use-code-generators"],
|
||||
"file": "shared/generators/composing-generators"
|
||||
"file": "shared/recipes/generators/composing-generators"
|
||||
},
|
||||
{
|
||||
"name": "Generator Options",
|
||||
"id": "generator-options",
|
||||
"tags": ["use-code-generators"],
|
||||
"file": "shared/generators/generator-options"
|
||||
"file": "shared/recipes/generators/generator-options"
|
||||
},
|
||||
{
|
||||
"name": "Creating Files",
|
||||
"id": "creating-files",
|
||||
"tags": ["use-code-generators"],
|
||||
"file": "shared/generators/creating-files"
|
||||
"file": "shared/recipes/generators/creating-files"
|
||||
},
|
||||
{
|
||||
"name": "Modifying Files",
|
||||
"id": "modifying-files",
|
||||
"tags": ["use-code-generators"],
|
||||
"file": "shared/generators/modifying-files"
|
||||
"file": "shared/recipes/generators/modifying-files"
|
||||
}
|
||||
]
|
||||
},
|
||||
@ -885,16 +885,34 @@
|
||||
"description": "Learn more about creating your own plugin, extending Nx.",
|
||||
"itemList": [
|
||||
{
|
||||
"name": "Project Inference Plugins",
|
||||
"id": "project-inference-plugins",
|
||||
"name": "Share Your Plugin",
|
||||
"id": "share-your-plugin",
|
||||
"tags": ["create-your-own-plugin"],
|
||||
"file": "shared/extending-nx/project-inference-plugins"
|
||||
"file": "shared/recipes/plugins/share-your-plugin"
|
||||
},
|
||||
{
|
||||
"name": "Create a Preset",
|
||||
"id": "create-preset",
|
||||
"tags": ["create-your-own-plugin"],
|
||||
"file": "shared/recipes/plugins/create-preset"
|
||||
},
|
||||
{
|
||||
"name": "Migration Generators",
|
||||
"id": "migration-generators",
|
||||
"tags": ["create-your-own-plugin"],
|
||||
"file": "shared/recipes/plugins/migration-generators"
|
||||
},
|
||||
{
|
||||
"name": "Project Graph Plugins",
|
||||
"id": "project-graph-plugins",
|
||||
"tags": ["create-your-own-plugin", "explore-graph"],
|
||||
"file": "shared/extending-nx/project-graph-plugins"
|
||||
"file": "shared/recipes/plugins/project-graph-plugins"
|
||||
},
|
||||
{
|
||||
"name": "Project Inference Plugins",
|
||||
"id": "project-inference-plugins",
|
||||
"tags": ["create-your-own-plugin"],
|
||||
"file": "shared/recipes/plugins/project-inference-plugins"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@ -1,4 +1,6 @@
|
||||
Nx plugins are npm packages that contain generators and executors to extend a Nx workspace. Generators are blueprints to create new files from templates, and executors run those files. These plugins also update the `nx.json` when generating new libs or apps.
|
||||
Nx plugins are npm packages that contain [generators](/plugin-features/use-code-generators) and [executors](/plugin-features/use-task-executors) to extend a Nx workspace.
|
||||
|
||||
At its core, a generator is a function that creates or modifies code and an executor is a function that processes code. Nx makes it easier to call those functions from the terminal or through the [Nx Console UI](/core-features/integrate-with-editors). And you can use helper utils in the [Nx Devkit](/packages/devkit) to help build your generator or executor.
|
||||
|
||||
> A list of plugins that is maintained by Nrwl is found in the [Nrwl/nx repo](https://github.com/nrwl/nx/tree/master/packages). \
|
||||
> A list of custom plugins created by the community is found in the [Community](/community) section.
|
||||
@ -21,7 +23,7 @@ npx create-nx-plugin my-org --pluginName my-plugin
|
||||
|
||||
This command creates a brand-new workspace, and sets up a pre-configured plugin with the specified name.
|
||||
|
||||
> Note, the command above will create a plugin the package name set to `@my-org/my-plugin`. You can pass `--importPath` to provide a different package name.
|
||||
> Note, the command above will create a plugin with the package name set to `@my-org/my-plugin`. You can pass `--importPath` to provide a different package name.
|
||||
|
||||
> If you do not want to create a new workspace, install the `@nrwl/nx-plugin` dependency in an already existing workspace with npm or yarn. Then run `nx g @nrwl/nx-plugin:plugin [pluginName]`.
|
||||
|
||||
@ -153,120 +155,3 @@ To make sure that assets are copied to the dist folder, open the plugin's `proje
|
||||
## Using your Nx Plugin
|
||||
|
||||
To use your plugin, simply list it in `nx.json` or use its generators and executors as you would for any other plugin. This could look like `nx g @my-org/my-plugin:lib` for generators or `"executor": "@my-org/my-plugin:build"` for executors. It should be usable in all of the same ways as published plugins in your local workspace immediately after generating it. This includes setting it up as the default collection in `nx.json`, which would allow you to run `nx g lib` and hit your plugin's generator.
|
||||
|
||||
## Publishing your Nx Plugin
|
||||
|
||||
In order to use your plugin in other workspaces or share it with the community, you will need to publish it to an npm registry. To publish your plugin follow these steps:
|
||||
|
||||
1. Build your plugin with the command `nx run my-plugin:build`
|
||||
1. `npm publish ./dist/package/my-plugin` and follow the prompts from npm.
|
||||
1. That's it!
|
||||
|
||||
{% callout type="warning" title="Version bump" %}
|
||||
Currently you will have to modify the `package.json` version by yourself or with a tool.
|
||||
{% /callout %}
|
||||
|
||||
After that, you can then install your plugin like any other npm package,
|
||||
`npm i -D @my-org/my-plugin` or `yarn add -D @my-org/my-plugin`.
|
||||
|
||||
### Listing your Nx Plugin
|
||||
|
||||
Nx provides a utility (`nx list`) that lists both core and community plugins. To submit your plugin, please follow the steps below:
|
||||
|
||||
- Fork the [Nx repo](https://github.com/nrwl/nx/fork) (if you haven't already)
|
||||
- Update the [`community/approved-plugins.json` file](https://github.com/nrwl/nx/blob/master/community/approved-plugins.json) with a new entry for your plugin that includes name, url and description
|
||||
- Use the following commit message template: `chore(core): nx plugin submission [PLUGIN_NAME]`
|
||||
- push your changes, and run `yarn submit-plugin`
|
||||
|
||||
> The `yarn submit-plugin` command automatically opens the Github pull request process with the correct template.
|
||||
|
||||
We will then verify the plugin, offer suggestions or merge the pull request!
|
||||
|
||||
## Preset
|
||||
|
||||
A Preset is a customization option which you provide when creating a new workspace. TS, Node, React are some internal presets that Nx provides by default.
|
||||
|
||||
{% youtube
|
||||
src="https://www.youtube.com/embed/yGUrF0-uqaU"
|
||||
title="Develop a Nx Preset for your Nx Plugin"
|
||||
width="100%" /%}
|
||||
|
||||
### Custom Preset
|
||||
|
||||
At its core a preset is a generator, which we can create inside of a plugin.
|
||||
If you **don't** have an existing plugin you can create one by running
|
||||
|
||||
```shell
|
||||
npx create-nx-plugin my-org --pluginName my-plugin
|
||||
```
|
||||
|
||||
To create our preset inside of our plugin we can run
|
||||
|
||||
```shell
|
||||
nx generate @nrwl/nx-plugin:generator --name=preset --project=happynrwl
|
||||
```
|
||||
|
||||
{% callout type="warning" title="Double check" %}
|
||||
The word `preset` is required for the name of this generator
|
||||
{% /callout %}
|
||||
|
||||
You should have a similar structure to this:
|
||||
|
||||
```text
|
||||
happynrwl/
|
||||
├── e2e
|
||||
├── jest.config.js
|
||||
├── jest.preset.js
|
||||
├── nx.json
|
||||
├── package-lock.json
|
||||
├── package.json
|
||||
├── packages
|
||||
│ └── happynrwl
|
||||
│ ├── src
|
||||
│ │ ├── executors
|
||||
│ │ ├── generators
|
||||
│ │ │ ├── happynrwl
|
||||
│ │ │ └── preset // <------------- Here
|
||||
│ │ └── index.ts
|
||||
├── tools
|
||||
└── tsconfig.base.json
|
||||
```
|
||||
|
||||
After the command is finished, the preset generator is created under the folder named **preset**.
|
||||
The **generator.ts** provides an entry point to the generator. This file contains a function that is called to perform manipulations on a tree that represents the file system. The **schema.json** provides a description of the generator, available options, validation information, and default values.
|
||||
|
||||
Here is the sample generator function which you can customize to meet your needs.
|
||||
|
||||
```typescript
|
||||
export default async function (tree: Tree, options: PresetGeneratorSchema) {
|
||||
const normalizedOptions = normalizeOptions(tree, options);
|
||||
addProjectConfiguration(tree, normalizedOptions.projectName, {
|
||||
root: normalizedOptions.projectRoot,
|
||||
projectType: 'application',
|
||||
sourceRoot: `${normalizedOptions.projectRoot}/src`,
|
||||
targets: {
|
||||
exec: {
|
||||
executor: 'nx:run-commands',
|
||||
options: {
|
||||
command: `node ${projectRoot}/src/index.js`,
|
||||
},
|
||||
},
|
||||
},
|
||||
tags: normalizedOptions.parsedTags,
|
||||
});
|
||||
addFiles(tree, normalizedOptions);
|
||||
await formatFiles(tree);
|
||||
}
|
||||
```
|
||||
|
||||
To get an in-depth guide on customizing/running or debugging your generator see [local generators](/recipes/generators/local-generators).
|
||||
|
||||
#### Usage
|
||||
|
||||
Before you are able to use your newly created preset you must package and publish it to a registry.
|
||||
|
||||
After you have published your plugin to a registry you can now use your preset when creating a new workspace
|
||||
|
||||
```shell
|
||||
npx create-nx-workspace my-workspace --preset=my-plugin-name
|
||||
```
|
||||
|
||||
@ -14,68 +14,51 @@ Many organizations use Nx without any plugins. If you are mainly interested in m
|
||||
|
||||
## Nx plugins
|
||||
|
||||
Nx plugins are npm packages that contain generators and executors to extend the capabilities of an Nx workspace.
|
||||
Nx plugins contain [executors](/plugin-features/use-task-executors) and [generators](/plugin-features/use-code-generators) to extend the capabilities of an Nx workspace. They can be shared as npm packages or referenced directly within a single repo.
|
||||
|
||||
Plugins have:
|
||||
{% personas %}
|
||||
|
||||
- **Generators**
|
||||
{% persona type="browse" title="Browse Existing Plugins" url="/community#plugin-directory" %}
|
||||
|
||||
- Generators automate making changes to the file system.
|
||||
- Anytime you run `nx generate ...`, you invoke a generator.
|
||||
- They are used to create/update applications, libraries, components, and more.
|
||||
Browse through plugins built by Nx and the community.
|
||||
|
||||
- **Executors**
|
||||
- [Plugin Directory](/community#plugin-directory)
|
||||
|
||||
- Executors define how to perform an action on a project.
|
||||
- You invoke an executor with `nx run ...` (or `nx test`, `nx build`).
|
||||
- They are used to build applications and libraries, test them, lint them, and more.
|
||||
{% /persona %}
|
||||
|
||||
- **Project Graph Extensions**
|
||||
{% persona type="create" title="Build a Plugin" url="/packages/nx-plugin" %}
|
||||
|
||||
- Plugins can provide a function `processProjectGraph` to add extra edges to the project graph.
|
||||
- This allows plugins to influence the behavior of `nx affected` and the project graph visualization.
|
||||
- See [project graph plugins](/recipes/advanced-plugins/project-graph-plugins) for more information.
|
||||
Build a plugin for use in your own repo or to share with others.
|
||||
|
||||
- **Project Inference Extensions**
|
||||
- [Build a plugin](/packages/nx-plugin)
|
||||
|
||||
- Plugins can provide an array of glob patterns, `projectFilePatterns` that are used to infer project information.
|
||||
- Plugins can provide a function `registerProjectTargets` that takes in one of the matched project files, and
|
||||
returns an object containing inferred targets from the file.
|
||||
- This allows plugins to add new projects to the workspace that aren't identified by `project.json` or `package.json` files, and infer extra
|
||||
targets without adding them into project configuration.
|
||||
{% /persona %}
|
||||
|
||||
All the core plugins are written using Nx Devkit, and you can use the same utilities to write your own generators and
|
||||
{% persona type="share" title="Share Your Plugin" url="/recipes/advanced-plugins/share-your-plugin" %}
|
||||
|
||||
Publish your plugin to npm and keep your plugin users up to date with migration generators.
|
||||
|
||||
- [Share your plugin](/recipes/advanced-plugins/share-your-plugin)
|
||||
|
||||
{% /persona %}
|
||||
|
||||
{% persona type="extend" title="Extend Core Nx Functionality" url="/recipes/advanced-plugins/project-graph-plugins" %}
|
||||
|
||||
Extend the Nx graph logic to understand other languages and custom setups.
|
||||
|
||||
- [Extend Core Nx Functionality](/recipes/advanced-plugins/project-graph-plugins)
|
||||
|
||||
{% /persona %}
|
||||
|
||||
{% /personas %}
|
||||
|
||||
All the core plugins are written using [Nx Devkit](/packages/devkit), and you can use the same utilities to write your own generators and
|
||||
executors.
|
||||
|
||||
{% callout type="check" title="Plugins!" %}
|
||||
The Nx team maintains a core set of plugins for many application and tooling frameworks. You can write [custom generators](/recipes/generators/local-generators) and [executors](/recipes/executors/creating-custom-executors) for your own workspace. You can also write your own plugin and share it with the community. The [Nx Plugin](/packages/nx-plugin) plugin provides guidance on how you can build your own custom plugins.
|
||||
The Nx team maintains a core set of plugins for many application and tooling frameworks. You can write [generators](/recipes/generators/local-generators) and [executors](/recipes/executors/creating-custom-executors) in a plugin to use in your own repo or share it with the community. The [Nx Plugin](/packages/nx-plugin) plugin provides guidance on how you can build your own custom plugins.
|
||||
{% /callout %}
|
||||
|
||||
### Local workspace plugins
|
||||
|
||||
Nx plugins can also be used in the workspace they are generated inside of. For example, if you generate a plugin with `nx g @nrwl/nx-plugin:plugin my-plugin --importPath @my-org/my-plugin`, you will be able to immediately make use of generators and executors within it. This would look like `nx g @my-org/my-plugin:lib` for generators or `"executor": "@my-org/my-plugin:build"` for executors.
|
||||
|
||||
If you are only planning on making use of generators, Nx provides workspace generators which can be used rather than whole plugins.
|
||||
|
||||
Generating a full plugin allows you to take advantage of all of the capabilities above, including project inference and graph extension, which is not possible when solely using workspace generators.
|
||||
|
||||
Additionally, your local plugin could be set as the default collection in `nx.json`, such that running `nx g lib` would call your workspace plugin's lib generator.
|
||||
|
||||
### Listing Nx plugins
|
||||
|
||||
Nx provides a list of installed and available plugins from Nrwl and community maintainers. Plugins maintained by Nrwl
|
||||
maintained are scoped under the `@nrwl` organization.
|
||||
|
||||
Use the `nx list` command to display all registered plugins.
|
||||
|
||||
Using the `nx list [plugin]` command displays the generators and executors provided by that package.
|
||||
|
||||
## Nx Devkit
|
||||
|
||||
The Nx Devkit is the underlying technology used to customize Nx to support different technologies and custom use-cases.
|
||||
It contains many utility functions for reading and writing files, updating configuration, working with Abstract Syntax
|
||||
Trees (ASTs), and more.
|
||||
|
||||
### Pay as you go
|
||||
|
||||
As with most things in Nx, the core of Nx Devkit is very simple. It only uses language primitives and immutable
|
||||
|
||||
101
docs/shared/recipes/plugins/create-preset.md
Normal file
101
docs/shared/recipes/plugins/create-preset.md
Normal file
@ -0,0 +1,101 @@
|
||||
## Preset
|
||||
|
||||
When you create a new nx workspace, you run the command: [`npx create-nx-workspace`](/packages/nx/documents/create-nx-workspace).
|
||||
This command accepts a `--preset` option, for example: `npx create-nx-workspace --preset=react-standalone`.
|
||||
This preset option is pointing to a special generator function (remember, a generator is a function that simplifies an entire code generation script into a single function) that Nx will call when this `npx create-nx-workspace` command is run, that will generate your initial workspace.
|
||||
|
||||
{% youtube
|
||||
src="https://www.youtube.com/embed/yGUrF0-uqaU"
|
||||
title="Develop a Nx Preset for your Nx Plugin"
|
||||
width="100%" /%}
|
||||
|
||||
### Custom Preset
|
||||
|
||||
At its core a preset is a generator, which we can create inside of a plugin.
|
||||
|
||||
All first-party Nx presets are built into nx itself, but you can [create your own plugin](/plugin-features/create-your-own-plugin) and create a generator with the magic name: `preset`. Once you've [published your plugin](/recipes/advanced-plugins/share-your-plugin) on npm, you can now run. the create-nx-workspace command with the preset option set to the name of your published package.
|
||||
|
||||
For example, take
|
||||
|
||||
```shell
|
||||
npx create-nx-workspace --preset=qwik-nx
|
||||
```
|
||||
|
||||
This command will create a new Qwik preset based on the [published npm package: `qwik-nx`](https://www.npmjs.com/package/qwik-nx). If we check this package's source code, we can see that it has a [generator named `preset`](https://github.com/qwikifiers/qwik-nx/tree/main/packages/qwik-nx/src/generators/preset).
|
||||
|
||||
If you **don't** have an existing plugin you can create one by running
|
||||
|
||||
```shell
|
||||
npx create-nx-plugin my-org --pluginName my-plugin
|
||||
```
|
||||
|
||||
To create our preset inside of our plugin we can run
|
||||
|
||||
```shell
|
||||
nx generate @nrwl/nx-plugin:generator --name=preset --project=happynrwl
|
||||
```
|
||||
|
||||
{% callout type="warning" title="Double check" %}
|
||||
The word `preset` is required for the name of this generator
|
||||
{% /callout %}
|
||||
|
||||
You should have a similar structure to this:
|
||||
|
||||
```text
|
||||
happynrwl/
|
||||
├── e2e
|
||||
├── jest.config.js
|
||||
├── jest.preset.js
|
||||
├── nx.json
|
||||
├── package-lock.json
|
||||
├── package.json
|
||||
├── packages
|
||||
│ └── happynrwl
|
||||
│ ├── src
|
||||
│ │ ├── executors
|
||||
│ │ ├── generators
|
||||
│ │ │ ├── happynrwl
|
||||
│ │ │ └── preset // <------------- Here
|
||||
│ │ └── index.ts
|
||||
├── tools
|
||||
└── tsconfig.base.json
|
||||
```
|
||||
|
||||
After the command is finished, the preset generator is created under the folder named **preset**.
|
||||
The **generator.ts** provides an entry point to the generator. This file contains a function that is called to perform manipulations on a tree that represents the file system. The **schema.json** provides a description of the generator, available options, validation information, and default values.
|
||||
|
||||
Here is the sample generator function which you can customize to meet your needs.
|
||||
|
||||
```typescript
|
||||
export default async function (tree: Tree, options: PresetGeneratorSchema) {
|
||||
const normalizedOptions = normalizeOptions(tree, options);
|
||||
addProjectConfiguration(tree, normalizedOptions.projectName, {
|
||||
root: normalizedOptions.projectRoot,
|
||||
projectType: 'application',
|
||||
sourceRoot: `${normalizedOptions.projectRoot}/src`,
|
||||
targets: {
|
||||
exec: {
|
||||
executor: 'nx:run-commands',
|
||||
options: {
|
||||
command: `node ${projectRoot}/src/index.js`,
|
||||
},
|
||||
},
|
||||
},
|
||||
tags: normalizedOptions.parsedTags,
|
||||
});
|
||||
addFiles(tree, normalizedOptions);
|
||||
await formatFiles(tree);
|
||||
}
|
||||
```
|
||||
|
||||
To get an in-depth guide on customizing/running or debugging your generator see [local generators](/recipes/generators/local-generators).
|
||||
|
||||
#### Usage
|
||||
|
||||
Before you are able to use your newly created preset you must package and publish it to a registry.
|
||||
|
||||
After you have published your plugin to a registry you can now use your preset when creating a new workspace
|
||||
|
||||
```shell
|
||||
npx create-nx-workspace my-workspace --preset=my-plugin-name
|
||||
```
|
||||
86
docs/shared/recipes/plugins/migration-generators.md
Normal file
86
docs/shared/recipes/plugins/migration-generators.md
Normal file
@ -0,0 +1,86 @@
|
||||
# Migration Generators
|
||||
|
||||
When your plugin is being used in other repos, it is helpful to provide migration generators to automatically update configuration files when your plugin makes a breaking change.
|
||||
|
||||
A migration generator is a normal generator that is triggered when a developer runs the `nx migrate` command.
|
||||
|
||||
## Create a Migration Generator
|
||||
|
||||
For this example, we'll create a new migration generator that updates repos to use `newExecutorName` instead of `oldExecutorName` in their targets. This migration will be applied when the run `nx migrate` to move up past version `2.0.1` of our plugin.
|
||||
|
||||
### 1. Generate a migration
|
||||
|
||||
```shell
|
||||
nx generate @nrwl/nx-plugin:migration 'Change Executor Name' --packageVersion=2.0.1 --project=pluginName --description='Changes the executor name from oldExecutorName to newExecutorName'
|
||||
```
|
||||
|
||||
This command will update the following files:
|
||||
|
||||
```json {% fileName="package.json" %}
|
||||
{
|
||||
"nx-migrations": {
|
||||
"migrations": "./migrations.json"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json {% fileName="migrations.json" %}
|
||||
{
|
||||
"generators": {
|
||||
"change-executor-name": {
|
||||
"version": "2.0.1",
|
||||
"description": "Changes the executor name from oldExecutorName to newExecutorName",
|
||||
"cli": "nx",
|
||||
"implementation": "./src/migrations/change-executor-name/change-executor-name"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
And it creates a blank generator under: `libs/pluginName/src/migrations/change-executor-name/change-executor-name.ts`
|
||||
|
||||
### 2. Write the Generator Code
|
||||
|
||||
```ts {% fileName="change-executor-name.ts" %}
|
||||
import { getProjects, Tree, updateProjectConfiguration } from '@nrwl/devkit';
|
||||
|
||||
export function changeExecutorNameToNewName(tree: Tree) {
|
||||
const projects = getProjects(tree);
|
||||
|
||||
for (const [name, project] of projects) {
|
||||
if (
|
||||
project.targets?.build?.executor === '@myorg/pluginName:oldExecutorName'
|
||||
) {
|
||||
project.targets.build.executor = '@myorg/pluginName:newExecutorName';
|
||||
updateProjectConfiguration(tree, name, project);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export default changeExecutorNameToNewName;
|
||||
```
|
||||
|
||||
## Update package.json dependencies
|
||||
|
||||
If you just need to change dependency versions, you can add some configuration options to the `migrations.json` file without making a full generator.
|
||||
|
||||
```json {% fileName="migrations.json" %}
|
||||
{
|
||||
"packageJsonUpdates": {
|
||||
// this can be any name
|
||||
"12.10.0": {
|
||||
// this is version at which the change will be applied
|
||||
"version": "12.10.0-beta.2",
|
||||
"packages": {
|
||||
// the name of the dependency to update
|
||||
"@testing-library/react": {
|
||||
// the version to set the dependency to
|
||||
"version": "11.2.6",
|
||||
// When true, the dependency will be added if it isn't there. When false, the dependency is skipped if it isn't already present.
|
||||
"alwaysAddToPackageJson": false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
31
docs/shared/recipes/plugins/share-your-plugin.md
Normal file
31
docs/shared/recipes/plugins/share-your-plugin.md
Normal file
@ -0,0 +1,31 @@
|
||||
# Share your Nx Plugin
|
||||
|
||||
In order to use your plugin in other workspaces or share it with the community, you will need to publish it to an npm registry. To publish your plugin follow these steps:
|
||||
|
||||
1. Build your plugin with the command `nx run my-plugin:build`
|
||||
1. `npm publish ./dist/package/my-plugin` and follow the prompts from npm.
|
||||
1. That's it!
|
||||
|
||||
{% callout type="warning" title="Version bump" %}
|
||||
Currently you will have to modify the `package.json` version by yourself or with a tool.
|
||||
{% /callout %}
|
||||
|
||||
After that, you can then install your plugin like any other npm package,
|
||||
`npm i -D @my-org/my-plugin` or `yarn add -D @my-org/my-plugin`.
|
||||
|
||||
## Listing your Nx Plugin
|
||||
|
||||
Nx provides a utility (`nx list`) that lists both core and community plugins. To submit your plugin, please follow the steps below:
|
||||
|
||||
- Fork the [Nx repo](https://github.com/nrwl/nx/fork) (if you haven't already)
|
||||
- Update the [`community/approved-plugins.json` file](https://github.com/nrwl/nx/blob/master/community/approved-plugins.json) with a new entry for your plugin that includes name, url and description
|
||||
- Use the following commit message template: `chore(core): nx plugin submission [PLUGIN_NAME]`
|
||||
- push your changes, and run `yarn submit-plugin`
|
||||
|
||||
> The `yarn submit-plugin` command automatically opens the Github pull request process with the correct template.
|
||||
|
||||
We will then verify the plugin, offer suggestions or merge the pull request!
|
||||
|
||||
## Write Migrations
|
||||
|
||||
Once other repos are using your plugin, it would help them if you write migrations to automatically update their configuration files whenever you make breaking changes. Read the [migration generators guide](/recipes/advanced-plugins/migration-generators) to find out how.
|
||||
@ -1,5 +1,8 @@
|
||||
import {
|
||||
CloudArrowDownIcon,
|
||||
DocumentMagnifyingGlassIcon,
|
||||
DocumentPlusIcon,
|
||||
ShareIcon,
|
||||
Squares2X2Icon,
|
||||
} from '@heroicons/react/24/outline';
|
||||
import Link from 'next/link';
|
||||
@ -12,6 +15,10 @@ export function Personas({ children }: { children: ReactNode }): JSX.Element {
|
||||
}
|
||||
|
||||
type PersonaType =
|
||||
| 'create'
|
||||
| 'share'
|
||||
| 'extend'
|
||||
| 'browse'
|
||||
| 'cache'
|
||||
| 'distribute'
|
||||
| 'javascript'
|
||||
@ -134,6 +141,31 @@ const typeMap: Record<
|
||||
</svg>
|
||||
),
|
||||
},
|
||||
create: {
|
||||
image: <DocumentPlusIcon role="img" className="h-6 w-6" />,
|
||||
},
|
||||
share: {
|
||||
image: <ShareIcon role="img" className="h-6 w-6" />,
|
||||
},
|
||||
extend: {
|
||||
image: (
|
||||
<svg
|
||||
role="img"
|
||||
viewBox="0 0 24 24"
|
||||
className="h-6 w-6"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
>
|
||||
<title>Nx</title>
|
||||
<path
|
||||
d="M11.987 14.138l-3.132 4.923-5.193-8.427-.012 8.822H0V4.544h3.691l5.247 8.833.005-3.998 3.044 4.759zm.601-5.761c.024-.048 0-3.784.008-3.833h-3.65c.002.059-.005 3.776-.003 3.833h3.645zm5.634 4.134a2.061 2.061 0 0 0-1.969 1.336 1.963 1.963 0 0 1 2.343-.739c.396.161.917.422 1.33.283a2.1 2.1 0 0 0-1.704-.88zm3.39 1.061c-.375-.13-.8-.277-1.109-.681-.06-.08-.116-.17-.176-.265a2.143 2.143 0 0 0-.533-.642c-.294-.216-.68-.322-1.18-.322a2.482 2.482 0 0 0-2.294 1.536 2.325 2.325 0 0 1 4.002.388.75.75 0 0 0 .836.334c.493-.105.46.36 1.203.518v-.133c-.003-.446-.246-.55-.75-.733zm2.024 1.266a.723.723 0 0 0 .347-.638c-.01-2.957-2.41-5.487-5.37-5.487a5.364 5.364 0 0 0-4.487 2.418c-.01-.026-1.522-2.39-1.538-2.418H8.943l3.463 5.423-3.379 5.32h3.54l1.54-2.366 1.568 2.366h3.541l-3.21-5.052a.7.7 0 0 1-.084-.32 2.69 2.69 0 0 1 2.69-2.691h.001c1.488 0 1.736.89 2.057 1.308.634.826 1.9.464 1.9 1.541a.707.707 0 0 0 1.066.596zm.35.133c-.173.372-.56.338-.755.639-.176.271.114.412.114.412s.337.156.538-.311c.104-.231.14-.488.103-.74z"
|
||||
fill="white"
|
||||
/>
|
||||
</svg>
|
||||
),
|
||||
},
|
||||
browse: {
|
||||
image: <DocumentMagnifyingGlassIcon role="img" className="h-6 w-6" />,
|
||||
},
|
||||
};
|
||||
|
||||
export function Persona({
|
||||
|
||||
@ -15,12 +15,19 @@ export const persona: Schema = {
|
||||
},
|
||||
type: {
|
||||
type: 'String',
|
||||
default: 'zahra',
|
||||
default: 'integrated',
|
||||
required: true,
|
||||
matches: ['zahra', 'logan', 'harold'],
|
||||
matches: [
|
||||
'cache',
|
||||
'distribute',
|
||||
'javascript',
|
||||
'lerna',
|
||||
'react',
|
||||
'angular',
|
||||
'integrated',
|
||||
],
|
||||
errorLevel: 'critical',
|
||||
description:
|
||||
'Controls the color and image of the persona. Can be: "zahra", "logan", "harold".',
|
||||
description: 'Controls the icon of the persona.',
|
||||
},
|
||||
url: {
|
||||
type: 'String',
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user