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.json
output. - Additional assets for the output.
Setting up esbuild
To create a new workspace, run npx create-nx-workspace@latest --preset=npm
.
To add the esbuild plugin to an existing workspace, run the following:
❯
npm install -D @nx/esbuild
Creating a new JS library
You can add a new library that builds using esbuild with:
❯
nx g @nx/js:lib 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.
1"build": {
2 "executor": "@nx/esbuild:esbuild",
3 "options": {
4 //...
5 "assets": [
6 { "input": "libs/mylib", "glob": "README.md", "output": "/" },
7 { "input": "libs/mylib", "glob": "logo.png", "output": "/" },
8 { "input": "libs/mylib", "glob": "docs/**/*.md", "output": "/docs" },
9 //...
10 ]
11 }
12}
13
Running nx build mylib
outputs something like this.
1dist/libs/mylib/
2├── README.md
3├── docs
4│ ├── CONTRIBUTING.md
5│ └── TESTING.md
6├── index.js
7├── logo.png
8└── package.json
9
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.
1dist/libs/mylib/
2├── README.md
3├── index.js
4├── meta.json
5└── package.json
6
Custom esbuild options
Extra API options for esbuild can be passed in the esbuildOptions
object for your project configuration.
1"build": {
2 "executor": "@nx/esbuild:esbuild",
3 "options": {
4 //...
5 "esbuildOptions": {
6 "banner": { ".js": "// banner" },
7 "footer": { ".js": "// footer" }
8 }
9 }
10}
11