⚠️ Renaming ⚠️
Name might change in the future. Considering rollup-plugin-html-bundler ̇> (because we're basically transforming rollup into a tool for bundling html, might not even contain any JS in the end)

A(nother) rollup plugin that tries to teach Rollup to start from an HTML entry, and the use of (multiple) HTML files in general. The goal is to include assets referenced by the HTML file into the build-process as to copy/inline where appropriate and optionally optimize them. Without having to seperatly copy them to the output directory.

When building web-applications a HTML-file is simply the logical entry point into your application.
Inspired by (and forked from) the original @rollup/plugin-html, this plugin will also allow you to transform the source files by any HTML-templating engine such as handlebars.

Please see Supported Output Formats for information about using this plugin with output formats other than esm (es).

Requirements

This plugin aims to support active LTS versions Node versions v18, v20 + Rollup v3 and up

Install

Using npm:

npm install rollup-plugin-html-entry2 --save-dev

Usage

Create a rollup.config.js configuration file and import the plugin:

import html from 'rollup-plugin-html-entry2';

export default {
  input: 'src/index.html',
  output: {
    dir: 'output',
  },
  plugins: [html()]
};

!! To use 'import x from y' syntax you might need to set "type": "module" in your package.json. Javascript modules are the preferred way of writing modern Javascript. Due to the early stage development of this plugin, old-style CommonJS modules are completely ignored and unsupported for now.

Then call rollup either via the CLI or the API.

Options

`template`

Type: Function
Default: undefined
Returns: String

Specifies a transform to be applied before parsing the HTML, this allows you to transform the sourcefile with a templating engine such as handlebars first.

import {rollup} from "rollup";
import handlebars from "handlebars";
import html from "rollup-plugin-html-entry2";

async function build() {
    await rollup({
        input: 'index.hbs',
        plugins: [
            html({
                include: [
                    '**/*.(html|hbs)',// html or handlebars
                ],
                transform(src) {
                    return handlebars.compile(src)({a: 'a'})
                }
            })
        ]
    });
}

Supported Output Formats

By default, this plugin supports the esm (es). Any other format is currently untested as this plugin is in an early state, see #status

Status

(Rudimentarily) supported

Importing JS via <script src="..." type="module"> tags
Inline scripts (i.e <script>...</script>)
Compatibility with other plugins such as :
- @rollup/plugin-url including using it for <img src"..."/> references
- @rollup/plugin-node-resolve
- @rollup/plugin-babel
- @rollup/plugin-commonjs
- @rollup/plugin-typescript
- @rollup/plugin-terser
- rollup-plugin-livereload

Not (yet/properly) supported

Sourcemaps (inlined script) (dev-note: we're already including magic-string for this, but do not fully using it yet, neeeds refactoring)
Plugins importing CSS files
CommonJS (cjs) and IIFI output formats. (Is UMD actually ever used?)
Overriding which DOM-nodes and resulting URLS to ignore/include (in a clean way)
Other (various) plugins such as those for HMR etc
...

Contibuting

You can be helpful by testing, proving helpful feedback, expanding the documentation, responding to issues/questions being reported, resolving the many ToDo`s in the code, implementating features...
Get in touch or just dive into the code or issues.

See also the ToDo-list at the end of the changelog

Notes

git.cerxes.net

Once publicly released, the intent is to move the GIT-repository to github. Until that day though, it exists privately on this gitea server and corresponding npm-registry npm.cerxes.net.
TODO: change the links once this happens

Prior work

Vite seems to have already done work to handle HTML in rollup.
rollup-plugin-html-entry seems to be dead. Last version from 2020, there have been many changes to rollup`s plugin capabilities since then
@rollup/plugin-html is where this project was originally forked from. Its main focus was to generate an HTML to serve the resulting bundle. Which is different from supporting HTML as entry point since it did not resolve assets used in the HTML. Besides the project setup, not much of the original has been kept...
@web/rollup-plugin-html a plugin with similar intentions as this one (in active development anno 2023).

README.md

rollup-plugin-html-entry2

⚠️ WARNING: Experimental-stage plugin ⚠️