@craftamap/esbuild-plugin-html

@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

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.

Sample Configuration

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: `
            <!DOCTYPE html>
            <html lang="en">
            <head>
                <meta charset="UTF-8">
                <meta name="viewport" content="width=device-width, initial-scale=1.0">
            </head>
            <body>
                <div id="root">
                </div>
            </body>
            </html>
          `,
                },
                {
                    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: `
            <!DOCTYPE html>
            <html lang="en">
            <head>
                <meta charset="UTF-8">
                <meta name="viewport" content="width=device-width, initial-scale=1.0">
            </head>
            <body>
                You are using version <%- define.version %>
                <div id="root">
                </div>
            </body>
            </html>
          `,
                },
            ]
        })
    ]
}

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

Configuration

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<string, string>,
                                // 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

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
  </head>
  <body>
  </body>
</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