@craftamap/esbuild-plugin-html


!Simple banner containing the name of the project in a html self-closing tag

@craftamap/esbuild-plugin-html is a plugin to generate HTML files with
esbuild. All specified entry points, and their
related files (such as .css-files) are automatically injected into the HTML
file. @craftamap/esbuild-plugin-html is inspired by
jantimon/html-webpack-plugin.

Is any feature missing?
Please create a ticket.

Requirements

This plugin requires at least esbuild v0.12.26. The minimum node version
supported is Node.js 18.

Deno is officially not supported - however, it has been reported that the plugin
does work with Deno.

Installation

``bash
yarn add -D @craftamap/esbuild-plugin-html


or


npm install --save-dev @craftamap/esbuild-plugin-html
`

Usage

This plugin works by analyzing the
metafile esbuild provides. This
metafile contains information about all entryPoints and their output files.
This way, this plugin can map input files to their output file (javascript as
well as css).

craftamap/esbuild-plugin-html uses the jsdom
under the hood to create a model of your HTML from the provided template. In
this model, all discovered resources are injected. The plugin also uses lodash
templates to insert custom user
data into the template.

@craftamap/esbuild-plugin-html requires to have some options set in your
esbuild script:

- outdir must be set. The html files are generated within the outdir.
- metafile must be set to true (the plugin does this automatically, if it's
not set to false on purpose).

⚠️: you can set a specific output name for resources using esbuild's
entryNames feature. While this plugin tries to support this as best as it
can, it may or may not work reliable. If you encounter any issues with it,
please create a ticket.

$3

`javascript
const esbuild = require('esbuild');
const { htmlPlugin } = require('@craftamap/esbuild-plugin-html');

const options = {
entryPoints: ['src/index.jsx'],
bundle: true,
metafile: true, // needs to be set
outdir: 'dist/', // needs to be set
plugins: [
htmlPlugin({
files: [
{
entryPoints: [
'src/index.jsx',
],
filename: 'index.html',
htmlTemplate:

,
},
{
entryPoints: [
'src/auth/auth.jsx',
],
filename: 'auth.html',
title: 'Login',
scriptLoading: 'module',
favicon: './public/favicon.ico',
hash: true,
},
{
entryPoints: [
'src/installation/installation.jsx',
],
filename: 'installation.html',
title: 'title',
scriptLoading: 'module',
define: {
"version": "0.3.0",
},
htmlTemplate:







You are using version <%- define.version %>



,
},
]
})
]
}

esbuild.build(options).catch(() => process.exit(1))
`

$3

`typescript
interface Configuration {
files: HtmlFileConfiguration[],
}

interface HtmlFileConfiguration {
filename: string, // Output filename, e.g. index.html. This path is relative to the out dir
entryPoints: string[], // Entry points to inject into the created html file, e.g. ['src/index.jsx'].
// Multiple entryPoints are possible.
title?: string, // title to inject into the head, will not be set if not specified
htmlTemplate?: string, // custom html document template string. If you omit a template,
// a default template will be used (see below)
// can also be a relative path to an html file
define?: Record,
// Define custom values that can be accessed in the lodash template context
scriptLoading?: 'blocking' | 'defer' | 'module',
// Decide if the script tag will be inserted as blocking script tag,
// with defer="" (default) or with type="module"
favicon?: string, // path to favicon.ico. If not specified, no favicon will be injected
findRelatedCssFiles?: boolean,
// Find related output *.css-files and inject them into the html.
// Defaults to true.
findRelatedOutputFiles?: boolean,
// Find output files following the same name schema of the output file
// like (*.css)-files and inject them into the html. This option is deprecated,
// consider using findRelatedCssFiles.
// Defaults to false.
inline?: boolean | { // Inline all js and css entry points into the html file.
js?: boolean, // Inline all js resources into the html file.
css?: boolean, // Inline all css resources into the html file.
} | ((filepath: string) => boolean), // Inline resources by custom function.
// Not set by default - will not inline any resources.
extraScripts?: (string | { // accepts an array of src strings or objects with src and attributes
src: string; // src to use for the script
attrs?: { [key: string]: string } // attributes to append to the script, e.g. { type: 'module', async: true }
})[],
hash?: boolean | string, // Append a hash to all included scripts and CSS files for cache-busting. The
// hash is based on the given string. If given a boolean, the hash is based on
// the current time.
}
`

In case a publicPath is specified in the esbuild configuration,
esbuild-plugin-html will use absolute paths with the provided publicPath.

You can also change the verbosity of the plugin by changing esbuild's verbosity.

#### Default HTML template

`html








`

Contributing

Contributions are always welcome.

Currently tsc is used to build the project.

Commits should be messaged according to Conventional Commits.

Kudos: Other *.html-Plugins

There exist some other *.html-plugins for esbuild. Those work differently
than @craftamap/esbuild-plugin-html, and might be a better fit for you:

- @esbuilder/html -
loader-based approach (use *.html-file as entry point, and start
subprocesses with esbuild`)
- @chialab/esbuild-plugin-html
- loader-based approach