Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/webdiscus/html-bundler-webpack-plugin
Generates complete single-page or multi-page website from source assets. Supports Markdown, Eta, EJS, Handlebars, Nunjucks, Pug, Twig templates "out of the box". Resolves source files of scripts, styles, images in HTML.
https://github.com/webdiscus/html-bundler-webpack-plugin
bundler css ejs entry favicon handlebars html html-webpack-plugin integrity javascript loader markdown nunjucks preload scss style template twig webpack
Last synced: 6 days ago
JSON representation
Generates complete single-page or multi-page website from source assets. Supports Markdown, Eta, EJS, Handlebars, Nunjucks, Pug, Twig templates "out of the box". Resolves source files of scripts, styles, images in HTML.
- Host: GitHub
- URL: https://github.com/webdiscus/html-bundler-webpack-plugin
- Owner: webdiscus
- License: isc
- Created: 2023-01-06T22:36:21.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2025-01-18T20:48:40.000Z (14 days ago)
- Last Synced: 2025-01-19T03:55:49.094Z (14 days ago)
- Topics: bundler, css, ejs, entry, favicon, handlebars, html, html-webpack-plugin, integrity, javascript, loader, markdown, nunjucks, preload, scss, style, template, twig, webpack
- Language: JavaScript
- Homepage:
- Size: 60 MB
- Stars: 156
- Watchers: 7
- Forks: 15
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/html-bundler-webpack-plugin 'download npm package')
[](https://nodejs.org)
[](https://webpack.js.org)
[](https://github.com/webdiscus/html-bundler-webpack-plugin/actions/workflows/test.yml)
[](https://codecov.io/gh/webdiscus/html-bundler-webpack-plugin)
[](https://www.npmjs.com/package/html-bundler-webpack-plugin)
> This plugin is all you need to generate a complete single- or multi-page website from your source assets.
The plugin automates the processing of source files such as JS/TS, SCSS, images and other assets referenced in an HTML or template file.
This plugin will generate an HTML file containing all the necessary links to JS, CSS, images and other resources.
## Why use the HTML Bundler Plugin?
This plugin is a powerful alternative to [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) and a replacement for many [plugins and loaders](#list-of-plugins).
The HTML Bundler Plugin works a bit differently than `html-webpack-plugin`.
It doesn't just inject JavaScript and CSS into an HTML.
Instead, it resolves all the source files of the assets referenced directly in the template
and ensures the generated HTML contains the correct output URLs of resources after Webpack processes them.
Additionally, CSS extracted from styles imported in JS can be injected into HTML as a `` tag or as an inlined CSS.
---
📋 Table of Contents 🚀 Install and Quick Start 🖼 Usage examples 🔆 What's New
---
## 💡 Highlights
- An [entry point](#option-entry) is any HTML template. **Start from HTML**, not from JS.
- **Automatically** processes templates found in the [entry directory](#option-entry-path).
- Build-in support for [template engines](#template-engine): [Eta](#using-template-eta), [EJS](#using-template-ejs), [Handlebars](#using-template-handlebars), [Nunjucks](#using-template-nunjucks), [Pug](#using-template-pug), [Tempura](#using-template-tempura), [TwigJS](#using-template-twig), [LiquidJS](#using-template-liquidjs).
- Build-in support for **Markdown** `*.md` files in templates, see [Markdown demo](https://stackblitz.com/edit/markdown-to-html-webpack?file=webpack.config.js) in browser.
- **Source files** of [`script`](#option-js) and [`style`](#option-css) can be specified directly in HTML:
- ``\
No longer need to define source style files in Webpack entry or import styles in JavaScript.
- ``\
No longer need to define source JavaScript files in Webpack entry.
- **Resolves** [source files](#loader-option-sources) of assets in [attributes](#loader-option-sources-default) such as `href` `src` `srcset` using **relative path** or **alias**:
- ``
- `
`\
Source files will be resolved, processed and auto-replaced with correct URLs in the generated HTML.
- **Inlines** [JS](#recipe-inline-js), [CSS](#recipe-inline-css) and [Images](#recipe-inline-image) into HTML. See [how to inline all resources](#recipe-inline-all-assets-to-html) into single HTML file.
- Supports the [HMR for CSS](#option-css-hot) to update CSS in browser without a full reload.
- Watches for changes in the [data file](#option-entry-data) linked to the template in the plugin option.
- Generates the [preload](#option-preload) tags for fonts, images, video, scripts, styles.
- Generates the [integrity](#option-integrity) attribute in the `link` and `script` tags.
- Generates the [favicons](#favicons-bundler-plugin) of different sizes for various platforms.
- You can create custom plugins using the provided [Plugin Hooks](#plugin-hooks-and-callbacks).
- Over 600 [tests](https://github.com/webdiscus/html-bundler-webpack-plugin/tree/master/test) for various use cases.
See [full list of features](#features).
## HTML template as entry point
The **HTML Bundler** generates static HTML or [template function](#template-in-js) from [various templates](#template-engine) containing source files of scripts, styles, images, fonts and other resources, similar to how it works in [Vite](https://vitejs.dev/guide/#index-html-and-project-root).
This plugin looks at the template files in [entry option](#option-entry) to start building the bundle.
The [source files](#loader-option-sources) of dependencies (scripts, styles, etc.) can be defined directly in the template.
The plugin **resolves source files** of assets in templates and replaces them with correct output URLs in the generated HTML.
The resolved assets will be processed via Webpack plugins/loaders and placed into the output directory.
You can use a relative path or Webpack alias to a source file.
A template imported in JS will be compiled into [template function](#template-in-js). You can use the **template function** in JS to render the template with variables in runtime on the client-side in the browser.
For example, using source asset files is HTML template _./src/views/index.html_:
```html
Hello World!
```
The folder structure of the example:
```
./src/views/index.html
./src/app/main.ts
./src/scss/style.scss
./src/assets/images/picture1.png
./src/assets/images/picture2.png
```
Simple and clear Webpack configuration:
```js
const path = require('path');
const HtmlBundlerPlugin = require('html-bundler-webpack-plugin');
module.exports = {
output: {
path: path.resolve(__dirname, 'dist'),
},
plugins: [
new HtmlBundlerPlugin({
// specify the entry points for HTML pages (or a template)
entry: {
index: 'src/views/index.html', // save generated HTML into dist/index.html
},
js: {
filename: 'js/[name].[contenthash:8].js', // JS output filename
},
css: {
filename: 'css/[name].[contenthash:8].css', // CSS output filename
},
}),
],
module: {
rules: [
{
test: /\.s?css$/,
use: ['css-loader', 'sass-loader'],
},
{
test: /\.(ico|png|jpe?g|svg)/,
type: 'asset/resource',
},
],
},
};
```
See full list of all [plugin options](#toc-plugin-options).
[Open an example in StackBlitz](https://stackblitz.com/edit/hello-world-webpack?file=webpack.config.js)
---
> 🦖 **Mozilla** already uses this plugin to build static HTML files for the [Mozilla AI GUIDE](https://github.com/mozilla/ai-guide) site.
>
> The plugin has been actively developed for more than 2 years, and since 2023 it is open source.\
> Please support this project by giving it a star ⭐.
---
## ❤️ Sponsors & Patrons
Thank you to all our sponsors and patrons!
---
#### [↑ top](#top) | [↓ contents](#contents)
## ⚙️ How the plugin works
The plugin resolves references in the HTML template and adds them to the Webpack compilation.
Webpack will automatically process the source files, and the plugin replaces the references with their output filenames in the generated HTML.
See [how the plugin works under the hood](#plugin-hooks-and-callbacks).
## ❓Question / Feature Request / Bug
If you have discovered a bug or have a feature suggestion, feel free to create an [issue](https://github.com/webdiscus/html-bundler-webpack-plugin/issues) on GitHub.
## 📚 Read it
- [Using HTML Bundler Plugin for Webpack to generate HTML files](https://dev.to/webdiscus/using-html-bundler-plugin-for-webpack-to-generate-html-files-30gd)
- [Keep output directory structure in Webpack](https://dev.to/webdiscus/how-to-keep-the-folder-structure-of-source-templates-in-webpack-for-output-html-files-39bj)
- [Auto generate an integrity hash for `link` and `script` tags](https://dev.to/webdiscus/webpack-auto-generate-an-integrity-hash-for-link-and-script-tags-in-an-html-template-48p5)
- [Use a HTML file as an entry point?](https://github.com/webpack/webpack/issues/536) (Webpack issue, #536)
- [Comparison and Benchmarks of Node.js libraries to colorize text in terminal](https://dev.to/webdiscus/comparison-of-nodejs-libraries-to-colorize-text-in-terminal-4j3a) (_offtopic_)
## 🔆 What's New in v4
- **NEW** you can include Markdown `*.md` files in your HTML template (since `v4.6.0`).
- **NEW** added supports the [HMR for CSS](#option-css-hot) (since `v4.5.0`).
- **NEW** added supports the [multiple configurations](https://webpack.js.org/configuration/configuration-types/#exporting-multiple-configurations).
- **SUPPORTS** Webpack version `5.96+` (since `v4.2.0`).
- **SUPPORTS** Webpack version `5.81+` (since `v4.0.0`).
- **SUPPORTS** Node.js version `18+`.
- **BREAKING CHANGES** see in the [changelog](https://github.com/webdiscus/html-bundler-webpack-plugin/blob/master/CHANGELOG.md#v4-0-0).
## 🔆 What's New in v3
- **NEW** added supports the [template function](#template-in-js) in JS runtime on the client-side.
- **NEW** added [Pug](#using-template-pug) preprocessor.
- **NEW** added [Twig](#using-template-twig) preprocessor.
- **NEW** added supports the dynamic import of styles.
- **NEW** added supports the [CSS Modules](#recipe-css-modules) for styles imported in JS.
- **NEW** added CSS extraction from **styles** used in `*.vue` files.
- **NEW** added [Hooks & Callbacks](#plugin-hooks-and-callbacks). Now you can create own plugin to extend this plugin.
- **NEW** added the build-in [FaviconsBundlerPlugin](#favicons-bundler-plugin) to generate and inject favicon tags.
## 🔆 What's New in v2
- **NEW** added importing style files in JavaScript.
- **NEW** added support the [integrity](#option-integrity).
- **NEW** you can add/delete/rename a template file in the [entry path](#option-entry-path) without restarting Webpack.
For full release notes see the [changelog](https://github.com/webdiscus/html-bundler-webpack-plugin/blob/master/CHANGELOG.md).
## ⚠️ Limitations
### Cache type
The current version works stably with `cache.type` as `'memory'` (Webpack's default setting).
Support for the `'filesystem'` cache type is in beta.
It works stably in standard use cases, but it cannot be guaranteed to work in all use cases.
If you have any problems, feel free to create an [issue](https://github.com/webdiscus/html-bundler-webpack-plugin/issues).
---
#### [↑ top](#top) | [↓ contents](#contents)
## Install and Quick start
Install the `html-bundler-webpack-plugin`:
```bash
npm install html-bundler-webpack-plugin --save-dev
```
It's recommended to combine `html-bundler-webpack-plugin` with the [css-loader](https://github.com/webpack-contrib/css-loader) and the [sass-loader](https://github.com/webpack-contrib/sass-loader).\
Install additional packages for styles:
```bash
npm install css-loader sass-loader sass --save-dev
```
Start with an HTML template. Add the `` and `` tags.
You can include asset source files such as SCSS, JS, images, and other media files directly in an HTML template.
The plugin resolves `<script src="...">` `<link href="...">` and `<img src="..." srcset="...">` that references your script, style and image source files.
For example, there is the template _./src/views/home.html_:
```html
<html>
<head>
<!-- variable from Webpack config -->
<title><%= title %></title>
<!-- relative path to favicon source file -->
<link href="./favicon.ico" rel="icon" />
<!-- relative path to SCSS source file -->
<link href="./style.scss" rel="stylesheet" />
<!-- relative path to JS source file -->
<script src="./main.js" defer="defer">
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
(() => {
'use strict';
console.log('>> script.js');
})();
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
{% block content %}{% endblock %}
Breaking Bad
Breaking Bad is an American crime drama
Location: Albuquerque, New Mexico
Main characters
- Walter White, "Heisenberg"
- Jesse Pinkman