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.

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.

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 as-provided vs. derived 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.