Nx with esbuild

esbuild is an extremely fast JavaScript bundler. In an esbuild monorepo, Nx builds and caches projects across your workspace so only what changed gets rebuilt.

The Nx Plugin for esbuild runs these builds through the @nx/esbuild:esbuild executor, with type-checking and asset handling layered on top.

Requirements

The @nx/esbuild plugin supports the following package versions.

Package	Supported Versions
esbuild	>=0.19.2 <1.0.0

Nx generators install the latest supported versions automatically when scaffolding new projects.

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

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.

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

More documentation

• Using JS

Set up CI for your esbuild monorepo

In CI, Nx runs nx affected to rebuild and retest only the projects a change touches, and caches results to skip repeated work.

For a complete pipeline, see Set up CI.