[npm]: https://img.shields.io/npm/v/rollup-plugin-html-entry2
[npm-url]: https://www.npmjs.com/package/rollup-plugin-html-entry2
[size]: https://packagephobia.now.sh/badge?p=rollup-plugin-html-entry2
[size-url]: https://packagephobia.now.sh/result?p=rollup-plugin-html-entry2
[handlebars]: https://www.npmjs.com/package/handlebars
 

[![npm][npm]][npm-url]
[![size][size]][size-url]
[![libera manifesto](https://img.shields.io/badge/libera-manifesto-lightgrey.svg)](https://liberamanifesto.com)

# rollup-plugin-html-entry2
| :warning: 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](https://www.npmjs.com/package/@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](#supported-output-formats) for information about using this plugin with output formats other than `esm` (`es`).

## Requirements

This plugin requires an [LTS](https://github.com/nodejs/Release) Node version (v18.0.0+) and Rollup v3.?.?+.

## Install

Using npm:

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

## Usage

Create a `rollup.config.js` [configuration file](https://www.rollupjs.org/guide/en/#configuration-files) and import the plugin:

```js
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/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](https://www.rollupjs.org/guide/en/#command-line-reference) or the [API](https://www.rollupjs.org/guide/en/#javascript-api).

## Options

### `template`

Type: `Function`<br>
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. 

```javascript
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)

## Status

This plugin is in an early state. As such not everything that is supported yet, and the options 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


### Not (yet) supported
- Inline scripts (i.e `<script>...</script>`)
- Plugins importing CSS files
- CommonJS (cjs) and IIFI output formats. (Is UMD actually ever used?)
- Overriding which tags to ignore/include
- 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](mailto:rollup-plugin-html-entry2@cerxes.net) or just dive into [the code](https://git.cerxes.net/rollup-apps/plugin-html) or [issues](https://git.cerxes.net/rollup-apps/plugin-html/issues)

# 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](https://npm.cerxes.net).\
TODO: change the links once this happens
## Prior work
 - [Vite](https://vitejs.dev) 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](https://www.npmjs.com/package/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](https://www.npmjs.com/package/@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](https://www.npmjs.com/package/@web/rollup-plugin-html) a plugin with similar intentions as this one (in active development anno 2023).