Rescope @nrwl to @nx

@nx/esbuild

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

Nx 15 and lower use @nrwl/ instead of @nx/

Creating a new JS library

Directory Flag Behavior Changes

The command below uses the as-provided directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the derived option, omit the --directory flag. See the workspace layout documentation for more details.

You can add a new library that builds using esbuild with:

❯

nx g @nx/js:lib mylib --directory=libs/mylib --bundler=esbuild

Nx 15 and lower use @nrwl/ instead of @nx/

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

Nx 15 and lower use @nrwl/ instead of @nx/

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

Nx 15 and lower use @nrwl/ instead of @nx/

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
Nx 15 and lower use @nrwl/ instead of @nx/

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
Nx 15 and lower use @nrwl/ instead of @nx/

More Documentation

Package reference

Here is a list of all the executors and generators available from this package.

Guides

Executors

  • esbuild

    Bundle a package using EsBuild.

Generators

  • initInternal

    Initialize the @nrwl/esbuild plugin.

  • configuration

    Add esbuild configuration to a project.