Gathering detailed insights and metrics for @craftamap/esbuild-plugin-html
Gathering detailed insights and metrics for @craftamap/esbuild-plugin-html
esbuild plugin to generate HTML files
Installations
npm install @craftamap/esbuild-plugin-htmlDeveloper Guide
BETA
Typescript
No
Module System
CommonJS
Min. Node Version
>=18
Score
66.3
Supply Chain
89.1
Quality
77.1
Maintenance
100
Vulnerability
97.9
License
Releases
7
Languages
2
JavaScript
TypeScript
JavaScript (58.74%)
TypeScript (41.26%)
Developer
craftamap
Download Statistics
Total Downloads
1,885,584
Last Day
1,272
Last Week
23,315
Last Month
85,701
Last Year
825,377
GitHub Statistics
47 Stars
105 Commits
15 Forks
2 Watchers
19 Branches
8 Contributors
Updated on May 26, 2025
Bundle Size
2.65 MB
Minified
659.02 kB
Minified + Gzipped
Maintainers
1
Package Meta Information
Latest Version
0.9.0
Package Id
@craftamap/esbuild-plugin-html@0.9.0
Unpacked Size
26.97 kB
Size
7.76 kB
File Count
7
Published on
Mar 16, 2025
Total Downloads
Cumulative downloads
Total Downloads
1,885,584
Last Day
248.5%
1,272
Compared to previous day
Last Week
-12.9%
23,315
Compared to previous week
Last Month
18.8%
85,701
Compared to previous month
Last Year
17.2%
825,377
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Peer Dependencies
1
@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
1yarn add -D @craftamap/esbuild-plugin-html 2# or 3npm 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:
outdirmust be set. The html files are generated within theoutdir.metafilemust be set totrue(the plugin does this automatically, if it's not set tofalseon 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
1const esbuild = require('esbuild'); 2const { htmlPlugin } = require('@craftamap/esbuild-plugin-html'); 3 4const options = { 5 entryPoints: ['src/index.jsx'], 6 bundle: true, 7 metafile: true, // needs to be set 8 outdir: 'dist/', // needs to be set 9 plugins: [ 10 htmlPlugin({ 11 files: [ 12 { 13 entryPoints: [ 14 'src/index.jsx', 15 ], 16 filename: 'index.html', 17 htmlTemplate: ` 18 <!DOCTYPE html> 19 <html lang="en"> 20 <head> 21 <meta charset="UTF-8"> 22 <meta name="viewport" content="width=device-width, initial-scale=1.0"> 23 </head> 24 <body> 25 <div id="root"> 26 </div> 27 </body> 28 </html> 29 `, 30 }, 31 { 32 entryPoints: [ 33 'src/auth/auth.jsx', 34 ], 35 filename: 'auth.html', 36 title: 'Login', 37 scriptLoading: 'module', 38 favicon: './public/favicon.ico', 39 hash: true, 40 }, 41 { 42 entryPoints: [ 43 'src/installation/installation.jsx', 44 ], 45 filename: 'installation.html', 46 title: 'title', 47 scriptLoading: 'module', 48 define: { 49 "version": "0.3.0", 50 }, 51 htmlTemplate: ` 52 <!DOCTYPE html> 53 <html lang="en"> 54 <head> 55 <meta charset="UTF-8"> 56 <meta name="viewport" content="width=device-width, initial-scale=1.0"> 57 </head> 58 <body> 59 You are using version <%- define.version %> 60 <div id="root"> 61 </div> 62 </body> 63 </html> 64 `, 65 }, 66 ] 67 }) 68 ] 69} 70 71esbuild.build(options).catch(() => process.exit(1))
Configuration
1interface Configuration { 2 files: HtmlFileConfiguration[], 3} 4 5interface HtmlFileConfiguration { 6 filename: string, // Output filename, e.g. index.html. This path is relative to the out dir 7 entryPoints: string[], // Entry points to inject into the created html file, e.g. ['src/index.jsx']. 8 // Multiple entryPoints are possible. 9 title?: string, // title to inject into the head, will not be set if not specified 10 htmlTemplate?: string, // custom html document template string. If you omit a template, 11 // a default template will be used (see below) 12 // can also be a relative path to an html file 13 define?: Record<string, string>, 14 // Define custom values that can be accessed in the lodash template context 15 scriptLoading?: 'blocking' | 'defer' | 'module', 16 // Decide if the script tag will be inserted as blocking script tag, 17 // with `defer=""` (default) or with `type="module"` 18 favicon?: string, // path to favicon.ico. If not specified, no favicon will be injected 19 findRelatedCssFiles?: boolean, 20 // Find related output *.css-files and inject them into the html. 21 // Defaults to true. 22 findRelatedOutputFiles?: boolean, 23 // Find output files following the same name schema of the output file 24 // like (*.css)-files and inject them into the html. This option is deprecated, 25 // consider using findRelatedCssFiles. 26 // Defaults to false. 27 inline?: boolean | { // Inline all js and css entry points into the html file. 28 js?: boolean, // Inline all js resources into the html file. 29 css?: boolean, // Inline all css resources into the html file. 30 } | ((filepath: string) => boolean), // Inline resources by custom function. 31 // Not set by default - will not inline any resources. 32 extraScripts?: (string | { // accepts an array of src strings or objects with src and attributes 33 src: string; // src to use for the script 34 attrs?: { [key: string]: string } // attributes to append to the script, e.g. { type: 'module', async: true } 35 })[], 36 hash?: boolean | string, // Append a hash to all included scripts and CSS files for cache-busting. The 37 // hash is based on the given string. If given a boolean, the hash is based on 38 // the current time. 39}
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
1<!DOCTYPE html> 2<html> 3 <head> 4 <meta charset="utf-8" /> 5 </head> 6 <body> 7 </body> 8</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 withesbuild) - @chialab/esbuild-plugin-html
- loader-based approach
No vulnerabilities found.
No security vulnerabilities found.