@jgoz/esbuild-plugin-html
v1.0.6
Published
HTML plugin for esbuild
Downloads
431
Readme
@jgoz/esbuild-plugin-html
An esbuild plugin that populates an HTML template with <script> and <link> tags based on build output.
Note that this plugin is not necessary if you are using esbd, which has native support for HTML entry points.
Features
- Adds tags for JS and CSS output files
- Copies and rebases assets referenced by
<link>tags and inline<style>elements to output folder
Install
$ npm i @jgoz/esbuild-plugin-htmlUsage
Add it to your esbuild plugins:
const esbuild = require('esbuild');
const { htmlPlugin } = require('@jgoz/esbuild-plugin-html');
await esbuild.build({
// ...
plugins: [
htmlPlugin({
template: './src/index.html',
}),
],
});At the bare minimum, the provided template should have a doctype, html, head, and body, tags. script and link tags will be inserted appropriately depending on the scriptPlacement and linkPosition option values.
Plugin API
function htmlPlugin(options?: HtmlPluginOptions): Plugin
Plugin options:
| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| template (*) | string | - | Path to the HTML template to use (required).If a relative path is provided, it will be resolved relative to the absWorkingDir build option (falling back to process.cwd()). |
| chunks | "entry" \| (outputPath: string, output: Object) => boolean | "entry" | Filters chunks that should be included as <link> or <script> tags in the HTML output.If the string "entry" is given (default), all entry points defined in esbuild options will be included. Note that CSS entry points will only be included if they are specified explicitly in esbuild options; being dependencies of a JS entry point is not sufficient."chunks" may also be provided as a function that receives all outputs, not just entry points. Returning true will include a reference to the chunk in HTML, false will exclude it. |
| crossorigin | "anonymous" \| "use-credentials" | - | Defines how generated <link> and <script> tags handle cross-origin requests. |
| defer | boolean | - | Sets the defer attribute on generated script tags. |
| define | Record<string, string> | - | Values that will be substituted in the HTML output.Given the following value for define:define: { FOO: 'foo', BAR: 'bar', }The HTML template may use {{FOO}} and {{BAR}} wherever those values should be substituted.Note that unlike the define option in esbuild, strings should not be wrapped in JSON.stringify, since values will be substituted directly into the output. This means if any values are used in strings inside of inline <script> elements, they should be wrapped in quotes inside of the script. E.g.,html <script> const foo = "{{FOO}}"; </script> |
| filename | string | - | Output filename.By default, the filename will be the same as the basename of the template file. |
| ignoreAssets | boolean | - | By default, assets (images, manifests, scripts, etc.) referenced by <link>, <style> and <script> tags in the HTML template will be collected as esbuild assets if their src attributes are specified as relative paths. The asset paths will be resolved relative to the template file and will be copied to the output directory, taking publicPath into consideration if it has been set.Absolute paths or URIs will be ignored.To ignore all src attributes and avoid collecting discovered assets, set this option to true. |
| integrity | "sha256" \| "sha384" \| "sha512" | - | If specified, a cryptographic digest for each file referenced by a <link> or <script> tag will be calculated using the specified algorithm and added as an integrity attribute on the associated tag. |
| linkPosition | "above" \| "below" | "below" | Where to emit <link> elements for CSS chunks.Possible values:"above" — inside <head> element, above existing <link>s and <style>s"below" — inside <head> element, below existing <link>s and <style>s<link> elements are always emitted to <head>. |
| scriptPlacement | "head-above" \| "head-below" \| "body-above" \| "body-below" | "head-below" | Where to emit <script> elements for JS chunks.Possible values:"head-above" — inside <head> element, above existing <script>s"head-below" — inside <head> element, below existing <script>s"body-above" — inside <body> element, above existing <script>s"body-below" — inside <body> element, below existing <script>sWhen emitted to <head>, the defer option will be implicitly set to true. If you wish to disable this behavior, set defer: false. |
Example templates
Bare Minimum:
<!DOCTYPE html>
<html>
<head></head>
<body></body>
</html>With external referenced assets (will not be copied):
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="description" content="Description" />
<meta name="author" content="Me" />
<meta name="google" value="notranslate" />
<link
rel="apple-touch-icon"
sizes="180x180"
href="http://icons.com/icon.png"
/>
<meta name="theme-color" content="#ffffff" />
<meta
name="viewport"
content="width=device-width, user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1"
/>
<title>Complex Template</title>
<style type="text/css" media="screen, print"></style>
<link rel="stylesheet" href="https://google.com/fonts" />
<script>
window.global = window;
</script>
</head>
<body>
<div class="app-container"></div>
<script src="http://google.com/analytics"></script>
</body>
</html>With local referenced assets (will be copied):
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="description" content="Description" />
<meta name="author" content="Me" />
<meta name="google" value="notranslate" />
<link rel="apple-touch-icon" sizes="180x180" href="./assets/icon.png" />
<link rel="mask-icon" href="./assets/mask.svg" color="#5bbad5" />
<meta name="theme-color" content="#ffffff" />
<meta
name="viewport"
content="width=device-width, user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1"
/>
<title>Local Assets Template</title>
<style type="text/css" media="screen, print">
@font-face {
font-family: 'Open Sans';
font-weight: 400;
font-style: normal;
src: url('./assets/font.svg#OpenSans') format('svg');
}
body {
background: url(./assets/bg.png?test#foo);
content: 'url';
}
</style>
<link rel="stylesheet" href="https://google.com/fonts" />
<link rel="stylesheet" href="./assets/custom.css" />
<script>
window.global = window;
</script>
</head>
<body>
<div class="app-container"></div>
<script src="http://google.com/analytics"></script>
</body>
</html>With values that will be replaced by define option:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="description" content="Description" />
<meta name="author" content="Me" />
<meta name="google" value="notranslate" />
<link
rel="apple-touch-icon"
sizes="180x180"
href="http://icons.com/icon.png?{{ process.env.NODE_ENV }}"
/>
<meta name="theme-color" content="#ffffff" />
<meta
name="viewport"
content="width=device-width, user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1"
/>
<title>Complex Template</title>
<style type="text/css" media="screen, print"></style>
<link rel="stylesheet" href="https://google.com/fonts?{{ VERSION }}" />
<script>
window.global = window;
window.version = '{{VERSION}}';
window.environment = '{{process.env.NODE_ENV}}';
</script>
</head>
<body>
<div class="app-container"></div>
<script src="http://google.com/analytics"></script>
</body>
</html>