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 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.
"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" }
}
}
}