Custom ESBuild builders for Angular build facade
Allow customizing ESBuild configuration
Click to expand
npm i -D @angular-builders/custom-esbuild
- In your
angular.json
:Where:"projects": { ... "[project]": { ... "architect": { ... "[architect-target]": { "builder": "@angular-builders/custom-esbuild:[application|dev-server]", "options": { ... }
- [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 or dev-server
- 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 withng [architect-target]
- angular.json:
"projects": { ... "example-app": { ... "architect": { ... "build": { "builder": "@angular-builders/custom-esbuild:browser", "options": { ... }
- Run the build:
ng build
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
angular.json
:
"architect": {
...
"build": {
"builder": "@angular-builders/custom-esbuild:application",
"options": {
"plugins": ["./esbuild/plugins.ts", "./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
.
The plugin file can export either a single plugin or a list of plugins:
// esbuild/plugins.ts
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;
Or:
// esbuild/plugins.ts
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');
},
};
const updateExternalPlugin: Plugin = {
name: 'update-external',
setup(build: PluginBuild) {
const options = build.initialOptions;
options.external ??= [];
options.external.push('elysia');
},
};
export default [defineTextPlugin, updateExternalPlugin];
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.
angular.json
:
"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"
}
}
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:
(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>
.
The indexHtmlTransformer
function signature is defined here.
It is useful when you want to transform your index.html
according to the build options.
angular.json
:
"architect": {
...
"build": {
"builder": "@angular-builders/custom-esbuild:application",
"options": {
"indexHtmlTransformer": "./esbuild/index-html-transformer.js"
...
}
index-html-transformer.js
:
module.exports = (indexHtml) => {
const i = indexHtml.indexOf('</body>');
const content = `<p>Dynamically inserted content</p>`;
return `${indexHtml.slice(0, i)}
${content}
${indexHtml.slice(i)}`;
};
Alternatively, using TypeScript:
export default (indexHtml: string) => {
const i = indexHtml.indexOf('</body>');
const content = `<p>Dynamically inserted content</p>`;
return `${indexHtml.slice(0, i)}
${content}
${indexHtml.slice(i)}`;
};
In the example we add a paragraph with an example content to your index.html
. It is a very simple example without any asynchronous code but you can also return a Promise
from this function.
Custom ESBuild builder fully supports ESM.
- If your app has
"type": "module"
bothplugin.js
andindex-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. - For
"type": "commonjs"
(or unspecified type) bothplugin.js
andindex-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. - If you want to use TS config in ESM app, you must set the loader to
ts-node/esm
when runningng build
. Also, in that casetsconfig.json
forts-node
no longer defaults totsConfig
from theapplication
target - you have to specify it manually via environment variable. Example.
Note that tsconfig paths are not supported in TS configs within ESM apps. That is because tsconfig-paths do not support ESM.