Overview of the Nx esbuild Plugin

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 @nx/esbuild

Installation

In any Nx workspace, you can install @nx/esbuild by running the following command:

nx add @nx/esbuild

This will install the correct version of @nx/esbuild.

Using the @nx/esbuild Plugin

Creating a new JS library

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