GitHub - craftamap/esbuild-plugin-html: esbuild plugin to generate HTML files (original) (raw)

@craftamap/esbuild-plugin-html

npm

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 withesbuild. 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 byjantimon/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 themetafile 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 jsdomunder 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:

⚠️: you can set a specific output name for resources using esbuild'sentryNames 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

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: