8fa7065cf1
This PR updates examples in `.md` files (both docs and blog posts) to use positional args. Nx 20 changes the position arg to be either `directory` for apps/libs or `path` for artifacts (e.g. components). So before you'd do this: ``` nx g app myapp --directory=apps/myapp nx g lib mylib --directory=libs/mylib nx g lib mylib --directory=libs/nested/mylib nx g lib @acme/foo --directory=libs/@acme/foo --importPath=@acme/foo nx g component foo --directory=libs/ui/src/foo --pascalCaseFiles ``` Will now be simplified to ``` nx g app apps/myapp nx g lib libs/mylib nx g lib libs/nested/mylib nx g lib libs/@acme/foo # name and import path are both "@acme/foo" nx g component libs/ui/src/foo/Foo ``` For cases where `name` and `importPath` need to be changed, you can always manually specify them. ``` nx g lib libs/nested/foo # name is foo nx g lib libs/nested/foo --name=nested-foo # specify name with prefix nx g lib libs/@acme/foo --name # use "foo" as name and don't match importPath nx g lib libs/@internal/foo --importPath=@acme/foo # different importPath from name <!-- 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 <!-- This is the behavior we have today --> ## Expected Behavior <!-- This is the behavior we should expect with the changes in this PR --> ## Related Issue(s) <!-- Please link the issue being fixed so it gets closed when this is merged. --> Fixes #
4.1 KiB
| title | description |
|---|---|
| Overview of the Nx esbuild Plugin | The Nx Plugin for esbuild contains executors and generators that support building applications using esbuild. This page also explains how to configure esbuild on your Nx workspace. |
The Nx Plugin for esbuild, an extremely fast JavaScript bundler.
Why should you use this plugin?
- Fast builds using esbuild.
- Type-checking using TypeScript, which esbuild does not handle.
- Intelligent
package.jsonoutput. - Additional assets for the output.
Setting Up @nx/esbuild
Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the @nx/esbuild version that matches the version of nx in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can fix Nx version mismatches with this recipe.
{% /callout %}
In any Nx workspace, you can install @nx/esbuild by running the following command:
{% tabs %} {% tab label="Nx 18+" %}
nx add @nx/esbuild
This will install the correct version of @nx/esbuild.
{% /tab %} {% tab label="Nx < 18" %}
Install the @nx/esbuild package with your package manager.
npm add -D @nx/esbuild
{% /tab %} {% /tabs %}
Using the @nx/esbuild Plugin
Creating a new JS library
{% callout type="note" title="Directory Flag Behavior Changes" %}
The command below uses the as-provided directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the derived option, omit the --directory flag. See the as-provided vs. derived documentation for more details.
{% /callout %}
You can add a new library that builds using esbuild with:
nx g @nx/js:lib libs/mylib --bundler=esbuild
This command will install the esbuild plugin if needed, and set @nx/esbuild:esbuild executor for the build target.
Adding esbuild target to existing libraries
If you already have a JS project that you want to use esbuild for, run this command:
nx g @nx/esbuild:configuration mylib
This generator validates there isn't an existing build target. If you want to overwrite the existing target you can pass the --skipValidation option.
nx g @nx/esbuild:configuration mylib --skipValidation
Using esbuild
You can run builds with:
nx build mylib
Replace mylib with the name or your project. This command works for both applications and libraries.
Copying assets
Assets are non-JS and non-TS files, such as images, CSS, etc. You can add them to the project configuration as follows.
"build": {
"executor": "@nx/esbuild:esbuild",
"options": {
//...
"assets": [
{ "input": "libs/mylib", "glob": "README.md", "output": "/" },
{ "input": "libs/mylib", "glob": "logo.png", "output": "/" },
{ "input": "libs/mylib", "glob": "docs/**/*.md", "output": "/docs" },
//...
]
}
}
Running nx build mylib outputs something like this.
dist/libs/mylib/
├── README.md
├── docs
│ ├── CONTRIBUTING.md
│ └── TESTING.md
├── index.js
├── logo.png
└── package.json
Generating a metafile
A metafile can be generated by passing the --metafile option. This file contains information about the build that can be analyzed by other tools, such as bundle buddy.
nx build mylib --metafile
This command will generate a meta.json file in the output directory.
dist/libs/mylib/
├── README.md
├── index.js
├── meta.json
└── package.json
Custom esbuild options
Extra API options for esbuild can be passed in the esbuildOptions object for your project configuration.
"build": {
"executor": "@nx/esbuild:esbuild",
"options": {
//...
"esbuildOptions": {
"banner": { ".js": "// banner" },
"footer": { ".js": "// footer" }
}
}
}