@angular-builders/custom-esbuild 17.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Evgeny Barabanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# Custom ESBuild [builders](#builders) for Angular build facade
+
+[![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)
+
+Allow customizing ESBuild configuration
+
+# Table of Contents
+
+- [Usage](#usage)
+  - [For Example](#for-example)
+- [Builders](#builders)
+  - [Custom ESBuild `application`](#custom-esbuild-application)
+    - [Example](#example)
+  - [Custom ESBuild `dev-server`](#custom-esbuild-dev-server)
+    - [Example](#example)
+- [Index Transform](#index-transform)
+  - [Example](#example-2)
+- [ES Modules (ESM) Support](#es-modules-esm-support)
+
+# This documentation is for the latest major version only
+
+## Previous versions
+
+<details>
+  <summary>Click to expand</summary>
+
+- [Version 17](https://github.com/just-jeb/angular-builders/blob/17.x.x/packages/custom-esbuild/README.md)
+
+</details>
+
+## Prerequisites:
+
+- [Angular CLI 17.1](https://www.npmjs.com/package/@angular/cli)
+
+# Usage
+
+1.  `npm i -D @angular-builders/custom-esbuild`
+2.  In your `angular.json`:
+    ```js
+    "projects": {
+      ...
+      "[project]": {
+        ...
+        "architect": {
+          ...
+          "[architect-target]": {
+            "builder": "@angular-builders/custom-esbuild:[application|dev-server]",
+            "options": {
+              ...
+            }
+    ```
+    Where:
+    - [project] is the name of the project to which you want to add the builder
+    - [architect-target] is the name of build target you want to run (build, serve, test etc. or any custom target)
+    - [application|dev-server] one of the supported builders - [application](#Custom-webpack-browser) or [dev-server](#Custom-webpack-extract-i18n)
+3.  If `[architect-target]` is not one of the predefined targets (like build, serve, test etc.) then run it like this:  
+    `ng run [project]:[architect-target]`  
+    If it is one of the predefined targets, you can run it with `ng [architect-target]`
+
+## For Example
+
+- angular.json:
+  ```js
+  "projects": {
+    ...
+    "example-app": {
+      ...
+      "architect": {
+        ...
+        "build": {
+          "builder": "@angular-builders/custom-esbuild:browser",
+          "options": {
+            ...
+          }
+  ```
+- Run the build: `ng build`
+
+# Builders
+
+- [@angular-builders/custom-esbuild:application](#Custom-esbuild-application)
+- [@angular-builders/custom-esbuild:dev-server](#Custom-esbuild-dev-server)
+
+## Custom ESBuild `application`
+
+The `@angular-builders/custom-esbuild:application` builder is an extension of the `@angular-devkit/build-angular:application` builder, allowing the specification of additional properties on top of the existing ones. The custom builder runs the original builder at the end, incorporating extra parameters specified in the extended configuration. It will also perform `index.html` transformations if specified.
+
+Builder options:
+
+- All the `@angular-devkit/build-angular:application` options
+- `plugins`
+- `indexHtmlTransformer`: [see below](#index-transform)
+
+### Example
+
+`angular.json`:
+
+```js
+"architect": {
+  ...
+  "build": {
+    "builder": "@angular-builders/custom-esbuild:application",
+    "options": {
+      "plugins": ["./esbuild/plugin-1.js", "./esbuild/plugin-2.js"],
+      "indexHtmlTransformer": "./esbuild/index-html-transformer.js",
+      "outputPath": "dist/my-cool-client",
+      "index": "src/index.html",
+      "browser": "src/main.ts",
+      "polyfills": ["zone.js"],
+      "tsConfig": "src/tsconfig.app.json"
+    }
+```
+
+In the above example, we specify the list of `plugins` that should implement the ESBuild plugin schema. These plugins are custom user plugins and are added to the original ESBuild Angular configuration. Additionally, the `indexHtmlTransformer` property is used to specify the path to the file that exports the function used to modify the `index.html`.
+
+## Custom ESBuild `dev-server`
+
+The `@angular-builders/custom-esbuild:dev-server` is an enhanced version of the `@angular-devkit/build-angular:dev-server` builder that allows the specification of `middlewares` (Vite's `Connect` functions). It also obtains `plugins` and `indexHtmlTransformer` from the `:application` configuration to run the Vite server with all the necessary configuration applied.
+
+### Example
+
+`angular.json`:
+
+```js
+"architect": {
+  ...
+  "build": {
+    "builder": "@angular-builders/custom-esbuild:application",
+    "options": {
+      "plugins": ["./esbuild/plugin-1.js"]
+      ...
+    }
+  },
+  "serve": {
+    "builder": "@angular-builders/custom-esbuild:dev-server",
+    "options": {
+      "middlewares": ["./esbuild/my-middleware.js"],
+      "buildTarget": "my-project:build"
+    }
+  }
+```
+
+# Index Transform
+
+Since Angular 8, `index.html` is not generated as part of the build. If you want to modify your `index.html`, you should use the `indexHtmlTransformer` option. `indexHtmlTransformer` is a path (relative to the workspace root) to a `.js` or `.ts` file that exports a transformation function for `index.html`. If `indexHtmlTransformer` is written in TypeScript, the application's `tsConfig` file will be used by `tsnode` for its execution:
+
+```typescript
+(options: TargetOptions, indexHtmlContent: string) => string | Promise<string>;
+```
+
+or, in other words, the function receives target options and original `index.html` content (generated by Angular CLI) and returns a new content as `string` or `Promise<string>`.  
+`TargetOptions` follows `target` definition from [this](https://github.com/angular/angular-cli/blob/master/packages/angular_devkit/architect/src/input-schema.json) schema and looks like this:
+
+```typescript
+export interface Target {
+  configuration?: string;
+  project: string;
+  target: string;
+}
+```
+
+It is useful when you want to transform your `index.html` according to the build options.
+
+## Example
+
+`angular.json`:
+
+```js
+"architect": {
+  ...
+  "build": {
+    "builder": "@angular-builders/custom-esbuild:application",
+    "options": {
+      "indexHtmlTransformer": "./esbuild/index-html-transformer.js"
+      ...
+    }
+```
+
+`index-html-transformer.js`:
+
+```js
+module.exports = (targetOptions, indexHtml) => {
+  const i = indexHtml.indexOf('</body>');
+  const config = `<p>Configuration: ${targetOptions.configuration}</p>`;
+  return `${indexHtml.slice(0, i)}
+            ${config}
+            ${indexHtml.slice(i)}`;
+};
+```
+
+Alternatively, using TypeScript:
+
+```ts
+import { Target } from '@angular-devkit/architect/src/input-schema';
+import { json } from '@angular-devkit/core';
+
+type TargetOptions = json.JsonObject & Target;
+
+export default (targetOptions: TargetOptions, indexHtml: string) => {
+  const i = indexHtml.indexOf('</body>');
+  const config = `<p>Configuration: ${targetOptions.configuration}</p>`;
+  return `${indexHtml.slice(0, i)}
+            ${config}
+            ${indexHtml.slice(i)}`;
+};
+```
+
+In the example we add a paragraph with build configuration to your `index.html`. It is a very simple example without any asynchronous code but you can also return a `Promise` from this function.
+
+# ES Modules (ESM) Support
+
+Custom ESBuild builder fully supports ESM.
+
+- If your app has `"type": "module"` both `plugin.js` and `index-html-transformer.js` will be treated as ES modules, unless you change their file extension to `.cjs`. In that case they'll be treated as CommonJS Modules. [Example](../../examples/custom-esbuild/sanity-esbuild-app-esm).
+- For `"type": "commonjs"` (or unspecified type) both `plugin.js` and `index-html-transformer.js` will be treated as CommonJS modules unless you change their file extension to `.mjs`. In that case they'll be treated as ES Modules. [Example](../../examples/custom-esbuild/sanity-esbuild-app).
+- If you want to use TS config in ESM app, you must set the loader to `ts-node/esm` when running `ng build`. Also, in that case `tsconfig.json` for `ts-node` no longer defaults to `tsConfig` from the `application` target - you have to specify it manually via environment variable. [Example](../../examples/custom-esbuild/sanity-esbuild-app-esm/package.json#L9).  
+  _Note that tsconfig paths are not supported in TS configs within ESM apps. That is because [tsconfig-paths](https://github.com/dividab/tsconfig-paths) do not support ESM._

package/builders.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "./node_modules/@angular-devkit/architect/src/builders-schema.json",
+  "builders": {
+    "application": {
+      "implementation": "./dist/application",
+      "schema": "./dist/application/schema.json",
+      "description": "Build browser app extended with custom esbuild config"
+    },
+    "dev-server": {
+      "implementation": "./dist/dev-server",
+      "schema": "./dist/dev-server/schema.json",
+      "description": "Build browser app extended with custom esbuild config"
+    }
+  }
+}

package/dist/application/index.d.ts

@@ -0,0 +1,9 @@
+import { BuilderContext } from '@angular-devkit/architect';
+import { json } from '@angular-devkit/core';
+import { CustomEsbuildApplicationSchema } from '../custom-esbuild-schema';
+export declare function buildCustomEsbuildApplication(options: CustomEsbuildApplicationSchema, context: BuilderContext): import("rxjs").Observable<import("@angular-devkit/build-angular/src/builders/application").ApplicationBuilderOutput>;
+declare const _default: import("@angular-devkit/architect/src/internal").Builder<json.JsonObject & import("@angular-devkit/build-angular").ApplicationBuilderOptions & {
+    plugins?: string[];
+    indexHtmlTransformer?: string;
+}>;
+export default _default;

package/dist/application/index.js

@@ -0,0 +1,32 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCustomEsbuildApplication = void 0;
+const architect_1 = require("@angular-devkit/architect");
+const build_angular_1 = require("@angular-devkit/build-angular");
+const core_1 = require("@angular-devkit/core");
+const rxjs_1 = require("rxjs");
+const utils_1 = require("../utils");
+function buildCustomEsbuildApplication(options, context) {
+    const workspaceRoot = (0, core_1.normalize)(context.workspaceRoot);
+    const tsConfig = `${(0, core_1.getSystemPath)(workspaceRoot)}/${options.tsConfig}`;
+    return (0, rxjs_1.defer)(() => __awaiter(this, void 0, void 0, function* () {
+        const paths = options.plugins || [];
+        const codePlugins = yield Promise.all(paths.map(path => (0, utils_1.loadModule)(workspaceRoot, path, tsConfig, context.logger)));
+        const indexHtmlTransformer = options.indexHtmlTransformer
+            ? yield (0, utils_1.loadModule)(workspaceRoot, options.indexHtmlTransformer, tsConfig, context.logger)
+            : undefined;
+        return { codePlugins, indexHtmlTransformer };
+    })).pipe((0, rxjs_1.switchMap)(extensions => (0, build_angular_1.buildApplication)(options, context, extensions)));
+}
+exports.buildCustomEsbuildApplication = buildCustomEsbuildApplication;
+exports.default = (0, architect_1.createBuilder)(buildCustomEsbuildApplication);
+//# sourceMappingURL=index.js.map

package/dist/application/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/application/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,yDAA0E;AAC1E,iEAAiE;AACjE,+CAAsE;AAEtE,+BAAwC;AAGxC,oCAAsC;AAGtC,SAAgB,6BAA6B,CAC3C,OAAuC,EACvC,OAAuB;IAEvB,MAAM,aAAa,GAAG,IAAA,gBAAS,EAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,GAAG,IAAA,oBAAa,EAAC,aAAa,CAAC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAEvE,OAAO,IAAA,YAAK,EAAC,GAAS,EAAE;QACtB,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QACpC,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,GAAG,CACnC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAA,kBAAU,EAAS,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CACrF,CAAC;QAEF,MAAM,oBAAoB,GAAG,OAAO,CAAC,oBAAoB;YACvD,CAAC,CAAC,MAAM,IAAA,kBAAU,EAAC,aAAa,EAAE,OAAO,CAAC,oBAAoB,EAAE,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC;YACzF,CAAC,CAAC,SAAS,CAAC;QAEd,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAkC,CAAC;IAC/E,CAAC,CAAA,CAAC,CAAC,IAAI,CAAC,IAAA,gBAAS,EAAC,UAAU,CAAC,EAAE,CAAC,IAAA,gCAAgB,EAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;AACnF,CAAC;AAnBD,sEAmBC;AAED,kBAAe,IAAA,yBAAa,EAC1B,6BAA6B,CAC9B,CAAC"}