feat(custom-esbuild): allow providing ESBuild plugins (#1536)

closes #1617
closes #1537
closes #1288

README.md

@@ -28,7 +28,8 @@ Builders' and Angular **major** versions **must** match.
 
 # Builders
 
-- [Custom webpack builders](./packages/custom-webpack) (an alternative to `ng eject`) [![npm version](https://img.shields.io/npm/v/@angular-builders/custom-webpack.svg) ![npm (tag)](https://img.shields.io/npm/v/@angular-builders/custom-webpack/next.svg) ![npm](https://img.shields.io/npm/dm/@angular-builders/custom-webpack.svg)](https://www.npmjs.com/package/@angular-builders/custom-webpack)
+- [Custom esbuild builders](./packages/custom-esbuild) (Allow customizing ESBuild configuration) [![npm version](https://img.shields.io/npm/v/@angular-builders/custom-esbuild.svg) ![npm (tag)](https://img.shields.io/npm/v/@angular-builders/custom-esbuild/next.svg) ![npm](https://img.shields.io/npm/dm/@angular-builders/custom-esbuild.svg)](https://www.npmjs.com/package/@angular-builders/custom-esbuild)
+- [Custom webpack builders](./packages/custom-webpack) (Allow customizing Webpack configuration) [![npm version](https://img.shields.io/npm/v/@angular-builders/custom-webpack.svg) ![npm (tag)](https://img.shields.io/npm/v/@angular-builders/custom-webpack/next.svg) ![npm](https://img.shields.io/npm/dm/@angular-builders/custom-webpack.svg)](https://www.npmjs.com/package/@angular-builders/custom-webpack)
 - [Jest builder](./packages/jest) (allows running `ng test` with Jest) [![npm version](https://img.shields.io/npm/v/@angular-builders/jest.svg) ![npm (tag)](https://img.shields.io/npm/v/@angular-builders/jest/next.svg) ![npm](https://img.shields.io/npm/dm/@angular-builders/jest.svg)](https://www.npmjs.com/package/@angular-builders/jest)
 - [Bazel builder](./packages/bazel) (`ng` wrapper for `Bazel` build) [![npm version](https://img.shields.io/npm/v/@angular-builders/bazel.svg) ![npm (tag)](https://img.shields.io/npm/v/@angular-builders/bazel/next.svg) ![npm](https://img.shields.io/npm/dm/@angular-builders/bazel.svg)](https://www.npmjs.com/package/@angular-builders/bazek)
 - [Timestamp builder](./packages/timestamp) (an example builder from [this](https://medium.com/@justjeb/angular-cli-6-under-the-hood-builders-demystified-f0690ebcf01) article) [![npm version](https://img.shields.io/npm/v/@angular-builders/timestamp.svg) ![npm (tag)](https://img.shields.io/npm/v/@angular-builders/timestamp/next.svg) ![npm](https://img.shields.io/npm/dm/@angular-builders/timestamp.svg)](https://www.npmjs.com/package/@angular-builders/timestamp)

examples/bazel/package.json

@@ -7,6 +7,6 @@
   "private": true,
   "devDependencies": {
     "@angular-builders/bazel": "workspace:*",
-    "@angular/cli": "17.0.10"
+    "@angular/cli": "17.1.1"
   }
 }

examples/custom-esbuild/sanity-esbuild-app-esm/.editorconfig

@@ -0,0 +1,13 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

examples/custom-esbuild/sanity-esbuild-app-esm/.gitignore

@@ -0,0 +1,47 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+
+# compiled output
+/dist
+/tmp
+/out-tsc
+# Only exists if Bazel was run
+/bazel-out
+
+# dependencies
+/node_modules
+
+# profiling files
+chrome-profiler-events.json
+speed-measure-plugin.json
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+.history/*
+
+# misc
+/.angular/cache
+/.sass-cache
+/connect.lock
+/coverage
+/libpeerconnection.log
+npm-debug.log
+yarn-error.log
+testem.log
+/typings
+
+# System Files
+.DS_Store
+Thumbs.db

examples/custom-esbuild/sanity-esbuild-app-esm/angular.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "sanity-esbuild-app-esm": {
+      "projectType": "application",
+      "schematics": {
+        "@schematics/angular:component": {
+          "style": "scss"
+        }
+      },
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular-builders/custom-esbuild:application",
+          "options": {
+            "plugins": ["esbuild/define-text-plugin.js"],
+            "outputPath": "dist/sanity-esbuild-app-esm",
+            "index": "src/index.html",
+            "browser": "src/main.ts",
+            "polyfills": ["zone.js"],
+            "tsConfig": "tsconfig.app.json",
+            "inlineStyleLanguage": "scss",
+            "assets": ["src/favicon.ico", "src/assets"],
+            "styles": ["src/styles.scss"],
+            "scripts": []
+          },
+          "configurations": {
+            "production": {
+              "budgets": [
+                {
+                  "type": "initial",
+                  "maximumWarning": "500kb",
+                  "maximumError": "1mb"
+                },
+                {
+                  "type": "anyComponentStyle",
+                  "maximumWarning": "2kb",
+                  "maximumError": "4kb"
+                }
+              ],
+              "outputHashing": "all"
+            },
+            "esm": {
+              "plugins": ["esbuild/define-text-plugin.js"]
+            },
+            "cjs": {
+              "plugins": ["esbuild/define-text-plugin.cjs"]
+            },
+            "tsEsm": {
+              "plugins": ["esbuild/define-text-plugin.ts"]
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve": {
+          "builder": "@angular-builders/custom-esbuild:dev-server",
+          "options": {
+            "forceEsbuild": true,
+            "port": 5007
+          },
+          "configurations": {
+            "production": {
+              "buildTarget": "sanity-esbuild-app-esm:build:production"
+            },
+            "esm": {
+              "buildTarget": "sanity-esbuild-app-esm:build:esm",
+              "middlewares": ["esbuild/send-hello-middleware.js"]
+            },
+            "cjs": {
+              "buildTarget": "sanity-esbuild-app-esm:build:cjs",
+              "middlewares": ["esbuild/send-hello-middleware.cjs"]
+            },
+            "tsEsm": {
+              "buildTarget": "sanity-esbuild-app-esm:build:tsEsm",
+              "middlewares": ["esbuild/send-hello-middleware.ts"]
+            }
+          },
+          "defaultConfiguration": "cjs"
+        },
+        "test": {
+          "builder": "@angular-devkit/build-angular:karma",
+          "options": {
+            "polyfills": ["zone.js", "zone.js/testing"],
+            "tsConfig": "tsconfig.spec.json",
+            "karmaConfig": "karma.conf.cjs",
+            "inlineStyleLanguage": "scss",
+            "assets": ["src/favicon.ico", "src/assets"],
+            "styles": ["src/styles.scss"],
+            "scripts": []
+          }
+        },
+        "e2e": {
+          "builder": "@cypress/schematic:cypress",
+          "options": {
+            "devServerTarget": "sanity-esbuild-app-esm:serve",
+            "browser": "chrome",
+            "port": 4226
+          },
+          "configurations": {
+            "production": {
+              "devServerTarget": "sanity-esbuild-app-esm:serve:production"
+            },
+            "esm": {
+              "devServerTarget": "sanity-esbuild-app-esm:serve:esm"
+            },
+            "cjs": {
+              "devServerTarget": "sanity-esbuild-app-esm:serve:cjs"
+            },
+            "tsEsm": {
+              "devServerTarget": "sanity-esbuild-app-esm:serve:tsEsm"
+            }
+          },
+          "defaultConfiguration": "esm"
+        },
+        "cypress-run": {
+          "builder": "@cypress/schematic:cypress",
+          "options": {
+            "devServerTarget": "sanity-esbuild-app-esm:serve"
+          },
+          "configurations": {
+            "production": {
+              "devServerTarget": "sanity-esbuild-app-esm:serve:production"
+            }
+          }
+        },
+        "cypress-open": {
+          "builder": "@cypress/schematic:cypress",
+          "options": {
+            "watch": true,
+            "headless": false
+          }
+        }
+      }
+    }
+  }
+}

examples/custom-esbuild/sanity-esbuild-app-esm/cypress.config.js

@@ -0,0 +1,12 @@
+import { defineConfig } from 'cypress';
+
+export default defineConfig({
+  video: false,
+  screenshotOnRunFailure: false,
+  e2e: {
+    setupNodeEvents(on, config) {},
+    specPattern: 'e2e/src/**/*.e2e-spec.ts',
+    baseUrl: 'http://localhost:5001',
+    supportFile: false,
+  },
+});

examples/custom-esbuild/sanity-esbuild-app-esm/e2e/src/app.e2e-spec.ts

@@ -0,0 +1,23 @@
+import { AppPage } from './app.po';
+
+describe('workspace-project App', () => {
+  let page: AppPage;
+
+  beforeEach(() => {
+    page = new AppPage();
+  });
+
+  it('should display welcome message', () => {
+    page.navigateTo();
+    page
+      .getTitle()
+      .should(
+        'have.text',
+        'Welcome to sanity-esbuild-app-esm: This text is provided during the compilation!'
+      );
+  });
+
+  it('should display text from custom middleware', () => {
+    cy.visit('/send-hello').get('h1').should('have.text', 'Hello text from middleware!');
+  });
+});

examples/custom-esbuild/sanity-esbuild-app-esm/e2e/src/app.po.ts

@@ -0,0 +1,9 @@
+export class AppPage {
+  navigateTo() {
+    return cy.visit('/');
+  }
+
+  getTitle() {
+    return cy.get('app-root h1');
+  }
+}

examples/custom-esbuild/sanity-esbuild-app-esm/e2e/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "include": ["**/*.ts"],
+  "compilerOptions": {
+    "sourceMap": false,
+    "types": ["cypress"]
+  }
+}

examples/custom-esbuild/sanity-esbuild-app-esm/esbuild/define-text-plugin.cjs

@@ -0,0 +1,9 @@
+const defineTextPlugin = {
+  name: 'define-text',
+  setup(build) {
+    const options = build.initialOptions;
+    options.define.buildText = JSON.stringify('This text is provided during the compilation');
+  },
+};
+
+module.exports = defineTextPlugin;

examples/custom-esbuild/sanity-esbuild-app-esm/esbuild/define-text-plugin.js

@@ -0,0 +1,9 @@
+const defineTextPlugin = {
+  name: 'define-text',
+  setup(build) {
+    const options = build.initialOptions;
+    options.define.buildText = JSON.stringify('This text is provided during the compilation');
+  },
+};
+
+export default defineTextPlugin;

examples/custom-esbuild/sanity-esbuild-app-esm/esbuild/define-text-plugin.ts

@@ -0,0 +1,11 @@
+import type { Plugin, PluginBuild } from 'esbuild';
+
+const defineTextPlugin: Plugin = {
+  name: 'define-text',
+  setup(build: PluginBuild) {
+    const options = build.initialOptions;
+    options.define!['buildText'] = JSON.stringify('This text is provided during the compilation');
+  },
+};
+
+export default defineTextPlugin;

examples/custom-esbuild/sanity-esbuild-app-esm/esbuild/send-hello-middleware.cjs

@@ -0,0 +1,9 @@
+const sendHelloMiddleware = (req, res, next) => {
+  if (req.url === '/send-hello') {
+    res.end('<h1>Hello text from middleware!</h1>');
+  } else {
+    next();
+  }
+};
+
+module.exports = sendHelloMiddleware;

examples/custom-esbuild/sanity-esbuild-app-esm/esbuild/send-hello-middleware.js

@@ -0,0 +1,9 @@
+const sendHelloMiddleware = (req, res, next) => {
+  if (req.url === '/send-hello') {
+    res.end('<h1>Hello text from middleware!</h1>');
+  } else {
+    next();
+  }
+};
+
+export default sendHelloMiddleware;

examples/custom-esbuild/sanity-esbuild-app-esm/esbuild/send-hello-middleware.ts

@@ -0,0 +1,11 @@
+import type { NextHandleFunction } from 'connect';
+
+const sendHelloMiddleware: NextHandleFunction = (req, res, next) => {
+  if (req.url === '/send-hello') {
+    res.end('<h1>Hello text from middleware!</h1>');
+  } else {
+    next();
+  }
+};
+
+export default sendHelloMiddleware;

examples/custom-esbuild/sanity-esbuild-app-esm/karma.conf.cjs

@@ -0,0 +1,50 @@
+// Karma configuration file, see link for more information
+// https://karma-runner.github.io/1.0/config/configuration-file.html
+
+const path = require('path');
+process.env.CHROME_BIN = require('puppeteer').executablePath();
+
+module.exports = function (config) {
+  config.set({
+    basePath: '',
+    frameworks: ['jasmine', '@angular-devkit/build-angular'],
+    plugins: [
+      require('karma-jasmine'),
+      require('karma-chrome-launcher'),
+      require('karma-jasmine-html-reporter'),
+      require('karma-coverage'),
+      require('@angular-devkit/build-angular/plugins/karma'),
+    ],
+    client: {
+      clearContext: false, // leave Jasmine Spec Runner output visible in browser
+    },
+    coverageReporter: {
+      dir: path.join(__dirname, 'coverage', 'append-webpack-plugins'),
+      subdir: '.',
+      reporters: [
+        { type: 'text-summary' },
+        { type: 'html', subdir: 'html' },
+        { type: 'lcovonly' },
+        { type: 'json' },
+      ],
+    },
+    reporters: ['progress', 'kjhtml', 'coverage'],
+    port: 9876,
+    colors: true,
+    logLevel: config.LOG_INFO,
+    autoWatch: true,
+    flags: ['--disable-translate', '--disable-extensions'],
+    browsers: ['Chrome'],
+    browserConsoleLogOptions: {
+      terminal: false,
+    },
+    customLaunchers: {
+      ChromeHeadlessCI: {
+        base: 'ChromeHeadless',
+        flags: ['--no-sandbox', '--disable-gpu', '--disable-translate', '--disable-extensions'],
+      },
+    },
+    singleRun: true,
+    restartOnFileChange: true,
+  });
+};