129 lines
5.8 KiB
Markdown
129 lines
5.8 KiB
Markdown
[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]
|
|
[](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`\
|
|
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
|
|
### (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](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).
|
|
|
|
See also the ToDo-list at the end of the [changelog](./CHANGELOG.md)
|
|
|
|
|
|
# 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).
|