137 lines
3.0 KiB
Markdown
137 lines
3.0 KiB
Markdown
The Nx Plugin for [esbuild](https://esbuild.github.io/api/), 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](/packages/esbuild/executors/esbuild#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:
|
|
|
|
{% tabs %}
|
|
{% tab label="npm" %}
|
|
|
|
```shell
|
|
npm install -D @nx/esbuild
|
|
```
|
|
|
|
{% /tab %}
|
|
{% tab label="yarn" %}
|
|
|
|
```shell
|
|
yarn add -D @nx/esbuild
|
|
```
|
|
|
|
{% /tab %}
|
|
{% /tabs %}
|
|
|
|
### Creating a new JS library
|
|
|
|
You can add a new library that builds using esbuild with:
|
|
|
|
```shell
|
|
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:
|
|
|
|
```shell
|
|
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.
|
|
|
|
```shell
|
|
nx g @nx/esbuild:configuration mylib --skipValidation
|
|
```
|
|
|
|
## Using esbuild
|
|
|
|
You can run builds with:
|
|
|
|
```shell
|
|
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.
|
|
|
|
```jsonc
|
|
"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.
|
|
|
|
```text
|
|
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](https://www.bundle-buddy.com/esbuild).
|
|
|
|
```shell
|
|
nx build mylib --metafile
|
|
```
|
|
|
|
This command will generate a `meta.json` file in the output directory.
|
|
|
|
```text
|
|
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.
|
|
|
|
```jsonc
|
|
"build": {
|
|
"executor": "@nx/esbuild:esbuild",
|
|
"options": {
|
|
//...
|
|
"esbuildOptions": {
|
|
"banner": { ".js": "// banner" },
|
|
"footer": { ".js": "// footer" }
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## More Documentation
|
|
|
|
- [Using JS](/packages/js)
|