@clickup/ngx-esbuild

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:

• https://github.com/angular/angular/issues/43131
• https://github.com/angular/angular/issues/43165

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.

• inlineStyleLanguage
• optimization
• resourcesOutputPath
• aot
• vendorChunk
• commonChunk
• baseHref
• deployUrl
• verbose
• progress
• i18nMissingTranslation
• i18nDuplicateTranslation
• localize
• watch
• outputHashing
• poll
• deleteOutputPath
• preserveSymlinks
• extractLicenses
• buildOptimizer
• namedChunks
• subresourceIntegrity
• serviceWorker
• ngswConfigPath
• statsJson
• budgets
• crossOrigin
• allowedCommonJsDependencies

Local development

• Ensure you have Node 18 or higher installed
• Install pnpm: corepack enable
• Install local dev dependencies: pnpm install

Running tests

pnpm nx affected:test

Linting

pnpm nx affected:lint

Running the demo app

pnpm demo