plugin-html/README.md

rollup-plugin-html-entry2

⚠️ WARNING
Experimental-stage plugin. Expect bugs and missing features...

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 (and forked) by 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 requires an LTS Node version (v18.0.0+) and Rollup v3.?.?+.

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 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({
                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

This plugin is in an early state. As such not everything that is supported yet, the options are laregely undocumented and may change.

(Rudimentarily) supported

• Importing JS via <script src="..." type="module"> tags
• Importing assets using @rollup/plugin-url (which could use an update TBH)
• Compatibility with other plugins such as @rollup/plugin-node-resolve, @rollup/plugin-babel, @rollup/plugin-commonjs, @rollup/plugin-terser and rollup-plugin-livereload
• Inline scripts (i.e <script>...</script>)

Not (yet/properly) supported

• Sourcemaps (inlined script) (dev-note: we're already including magic-string for this, but do not use 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 typescript, or 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])(https://github.com/vitejs/vite/blob/main/packages/vite/src/node/plugins/html.ts) 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).