97b00840cc
<!-- Please make sure you have read the submission guidelines before posting an PR --> <!-- https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#-submitting-a-pr --> <!-- Please make sure that your commit message follows our format --> <!-- Example: `fix(nx): must begin with lowercase` --> <!-- If this is a particularly complex change or feature addition, you can request a dedicated Nx release for this pull request branch. Mention someone from the Nx team or the `@nrwl/nx-pipelines-reviewers` and they will confirm if the PR warrants its own release for testing purposes, and generate it for you if appropriate. --> ## Current Behavior Some plugin docs don't make sense after project name and root changes ## Expected Behavior They've been touched up ## Related Issue(s) <!-- Please link the issue being fixed so it gets closed when this is merged. --> Fixes #25191
93 lines
4.4 KiB
Markdown
93 lines
4.4 KiB
Markdown
# Create a Local Plugin
|
|
|
|
To get started with building a local Nx Plugin, install the `@nx/plugin` package and generate a plugin:
|
|
|
|
```shell
|
|
nx g @nx/plugin:plugin my-plugin --directory=tools/my-plugin
|
|
```
|
|
|
|
This will create a `my-plugin` project that contains all your plugin code and `my-plugin-e2e` for e2e tests.
|
|
|
|
> If you want to create a new workspace for your plugin, run `npx create-nx-plugin my-plugin`. This command will create a new workspace with `my-plugin` and `e2e` projects set up for you.
|
|
|
|
## Generator
|
|
|
|
To create a new generator run:
|
|
|
|
```shell
|
|
nx generate @nx/plugin:generator my-generator --directory="tools/my-plugin/src/generators/my-generator"
|
|
```
|
|
|
|
The new generator is located in `/src/generators/my-generator`. The `my-generator.ts` file contains the code that runs the generator. This generator creates a new project using a folder of template files.
|
|
|
|
For more information about this sample generator, read the [simple generator recipe](/extending-nx/recipes/local-generators).
|
|
|
|
### Generator options
|
|
|
|
The `schema.d.ts` file contains all the options that the generator supports. By default, it includes `directory`, `tags`, and `name` as the options. If more options need to be added, please update this file and the `schema.json` file.
|
|
|
|
{% callout type="note" title="More details" %}
|
|
The `schema.d.ts` file is used for type checking inside the implementation file. It should match the properties in `schema.json`.
|
|
{% /callout %}
|
|
|
|
### Generator Testing
|
|
|
|
The generator spec file includes boilerplate to help get started with testing. This includes setting up an empty workspace.
|
|
|
|
These tests should ensure that files within the tree (created with `createTreeWithEmptyWorkspace`) are in the correct place, and contain the right content.
|
|
|
|
Full E2Es are supported and will run everything on the file system like a user would.
|
|
|
|
## Executor
|
|
|
|
To create a new executor run:
|
|
|
|
```shell
|
|
nx generate @nx/plugin:executor my-executor --project=my-plugin
|
|
```
|
|
|
|
The new executor is located in `/src/executors/my-executor`. The `my-executor.ts` file contains the code that runs the executor. This executor emits a console log, but executors can compile code, deploy an app, publish to NPM and much more.
|
|
|
|
For more information about this sample executor, read the [simple executor recipe](/extending-nx/recipes/local-executors).
|
|
|
|
### Executor testing
|
|
|
|
The executor spec file contains boilerplate to run the default exported function from the executor.
|
|
|
|
These tests should make sure that the executor is executing and calling the functions that it relies on. Typically, unit tests are more useful for generators and e2e tests are more useful for executors.
|
|
|
|
## Testing your plugin
|
|
|
|
One of the biggest benefits that the Nx Plugin package provides is support for E2E and unit testing.
|
|
|
|
When the E2E app runs, a temporary E2E directory is created in the root of the workspace. This directory is a blank Nx workspace, and will have the plugin's built package installed locally.
|
|
|
|
### E2E Testing file
|
|
|
|
When the plugin is generated, a test file is created in the `my-plugin-e2e` app. Inside this test file, there is a disabled test that gives you a starting point for writing your own tests. To enable the test, change `xit` to `it`.
|
|
|
|
We'll go over a few parts of a test file below:
|
|
|
|
```typescript
|
|
beforeAll(() => {
|
|
ensureNxProject('my-plugin', 'dist/./.');
|
|
});
|
|
|
|
xit('should be able to build generated projects', async () => {
|
|
const name = 'proj';
|
|
const generator = 'PLACEHOLDER';
|
|
await runNxCommandAsync(`generate my-plugin:${generator} --name ${name}`);
|
|
expect(() => runNxCommand('build ${proj}')).not.toThrow();
|
|
expect(() => checkFilesExist(`dist/${name}/index.js`)).not.toThrow();
|
|
});
|
|
```
|
|
|
|
- The `ensureNxProject` is the function that will create the temporary directory. It takes two arguments, the plugin package name and the dist directory of when it's built.
|
|
- The `runNxCommandAsync` function will execute a `nx` command in the E2E directory.
|
|
|
|
There are additional functions that the `@nx/plugin/testing` package exports. Most of them are file utilities to manipulate and read files in the E2E directory.
|
|
|
|
## Using your Nx Plugin Locally
|
|
|
|
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.
|