@clickup/ngx-esbuild NPM

ngx-esbuild

ClickUp's esbuild powered local dev server, open sourced so you can speed up developing your own Angular applications!

About

This is an alternative local development environment for large Angular applications, powered by esbuild.

It makes a different set of trade-offs than the official Angular CLI esbuild solution to achieve faster build times and use less memory, namely:

It does not typecheck your code
As it does not typecheck, it cannot AoT compile your code either
It is designed for local development only, and does not support building for production

It mainly works by implementing a version of these 2 ideas:

Hopefully one day, the Angular CLI will support some of this out of the box, but until then, this is a great alternative.

Why would I use this?

You have a large Angular application
Local dev rebuilds are slow or use too much memory
You are not using buildable libraries or module federation
AOT / Typechecking is not essential
You've already tried the Angular CLI's esbuild solution and it's not fast enough for you

Getting Started

!IMPORTANT
Currently this only works with Nx workspaces, but we're planning on making it work with regular Angular CLI projects as well. See https://github.com/clickup/ngx-esbuild/issues/3 for more info.

Install with your favorite package manager:

npm install -D @clickup/ngx-esbuild

Add a new target to your apps project.json (assuming you have a build target using the @angular-devkit/build-angular:browser or @angular-devkit/build-angular:browser-esbuild executors):

"targets": {
  ... other targets ...
  "serve-esbuild": {
    "executor": "@clickup/ngx-esbuild:build",
    "options": {
      "serve": true
    }
  }
}

Run with nx serve-esbuild <project-name> to start the dev server powered by esbuild!

Typechecking

The builder is fast as it makes a different set of trade-offs than the Angular CLI esbuild solution. Namely, it doesn't do any typechecking.

While showing type errors in your IDE works to some extent, you probably want to still be able to typecheck your entire project.

So to enable typechecking, you can add another target like this:

"type-check": {
  "executor": "nx:run-commands",
  "options": {
    "command": "npx tsc -p apps/your-app/tsconfig.app.json --noEmit --watch --incremental --pretty"
  }
}

Then run with nx type-check <project-name>

If you want to type-check component templates, you can run the same command but replace tsc with ngc instead (this will use a much larger amount of memory though and may be more likely to cause performance problems):

"command": "npx ngc -p apps/your-app/tsconfig.app.json --noEmit --watch --incremental --pretty"

You can even run the dev server + typechecking side by side using stmux:

stmux -e '' -- [ "nx serve-esbuild demo" .. "nx type-check demo" ]

Supported angular devkit options

These options will be read from the existing build target that uses the angular devkit builder.

Supported

Many of these options only support a subset of different ways that they can be configured by the Angular CLI. If something doesn't work in your project, please file an issue and we can probably add support!

assets (partially supported)
main
polyfills
tsConfig
scripts (partially supported)
styles (partially supported)
stylePreprocessorOptions (only scss is supported currently)
fileReplacements (partially supported)
outputPath
sourceMap (partially supported)
index (partially supported)
webWorkerTsConfig

Unsupported (none of these options will have any effect)

This solution is intended to only ever work for local development, and will never support building for production. So, any options related to production builds will never be supported, for everything else it may be possible to add support in the future.