First private release. Check updated README.md for details
Some checks failed
continuous-integration/drone/push Build is failing
Some checks failed
continuous-integration/drone/push Build is failing
This commit is contained in:
184
README.md
184
README.md
@@ -1,33 +1,41 @@
|
||||
# Work-in-progress changelog
|
||||
|
||||
|
||||
|
||||
|
||||
[npm]: https://img.shields.io/npm/v/@rollup/plugin-html
|
||||
[npm-url]: https://www.npmjs.com/package/@rollup/plugin-html
|
||||
[size]: https://packagephobia.now.sh/badge?p=@rollup/plugin-html
|
||||
[size-url]: https://packagephobia.now.sh/result?p=@rollup/plugin-html
|
||||
[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
|
||||
# rollup-plugin-html-entry2
|
||||
| :warning: WARNING |
|
||||
|:-------------------------------------------------------------------|
|
||||
| **Experimental-stage** plugin. Expect bugs and missing features... |
|
||||
|
||||
🍣 A Rollup plugin which creates HTML files to serve Rollup bundles.
|
||||
|
||||
Please see [Supported Output Formats](#supported-output-formats) for information about using this plugin with output formats other than `esm` (`es`), `iife`, and `umd`.
|
||||
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 (v14.0.0+) and Rollup v1.20.0+.
|
||||
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 --save-dev
|
||||
npm install rollup-plugin-html-entry2 --save-dev
|
||||
```
|
||||
|
||||
## Usage
|
||||
@@ -35,131 +43,85 @@ npm install @rollup/plugin-html --save-dev
|
||||
Create a `rollup.config.js` [configuration file](https://www.rollupjs.org/guide/en/#configuration-files) and import the plugin:
|
||||
|
||||
```js
|
||||
const html = require('@rollup/plugin-html');
|
||||
import html from 'rollup-plugin-html-entry2';
|
||||
|
||||
module.exports = {
|
||||
input: 'src/index.js',
|
||||
export default {
|
||||
input: 'src/index.html',
|
||||
output: {
|
||||
dir: 'output',
|
||||
format: 'cjs'
|
||||
},
|
||||
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).
|
||||
|
||||
Once run successfully, an HTML file should be written to the bundle output destination.
|
||||
|
||||
## Options
|
||||
|
||||
### `attributes`
|
||||
|
||||
Type: `Object`<br>
|
||||
Default: `{ html: { lang: 'en' }, link: null, script: null }`
|
||||
|
||||
Specifies additional attributes for `html`, `link`, and `script` elements. For each property, provide an object with key-value pairs that represent an HTML element attribute name and value. By default, the `html` element is rendered with an attribute of `lang="en"`.
|
||||
|
||||
_Note: If using the `es` / `esm` output format, `{ type: 'module'}` is automatically added to `attributes.script`._
|
||||
|
||||
### `fileName`
|
||||
|
||||
Type: `String`<br>
|
||||
Default: `'index.html'`
|
||||
|
||||
### `meta`
|
||||
|
||||
Type: `Array[...object]`<br>
|
||||
Default: `[{ charset: 'utf-8' }]`
|
||||
|
||||
Specifies attributes used to create `<meta>` elements. For each array item, provide an object with key-value pairs that represent `<meta>` element attribute names and values.
|
||||
|
||||
Specifies the name of the HTML to emit.
|
||||
|
||||
### `publicPath`
|
||||
|
||||
Type: `String`<br>
|
||||
Default: `''`
|
||||
|
||||
Specifies a path to prepend to all bundle assets (files) in the HTML output.
|
||||
|
||||
### `template`
|
||||
|
||||
Type: `Function`<br>
|
||||
Default: `internal function`
|
||||
Default: `undefined`\
|
||||
Returns: `String`
|
||||
|
||||
Specifies a function that provides the rendered source for the HTML output. The function should be in the form of:
|
||||
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.
|
||||
|
||||
```js
|
||||
const template = ({ attributes, bundle, files, publicPath, title }) => { ... }
|
||||
```
|
||||
```javascript
|
||||
import {rollup} from "rollup";
|
||||
import handlebars from "handlebars";
|
||||
import html from "rollup-plugin-html-entry2";
|
||||
|
||||
- `attributes`: Corresponds to the `attributes` option passed to the plugin
|
||||
- `bundle`: An `Object` containing key-value pairs of [`AssetInfo` or `ChunkInfo`](https://rollupjs.org/guide/en/#generatebundle)
|
||||
- `files`: An `Array` of `AssetInfo` or `ChunkInfo` containing any entry (`isEntry: true`) files, and any asset (`isAsset: true`) files in the bundle that will be emitted
|
||||
- `publicPath`: Corresponds to the `publicPath` option passed to the plugin
|
||||
- `title`: Corresponds to the `title` option passed to the plugin
|
||||
|
||||
By default this is handled internally and produces HTML in the following format:
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html ${attributes}>
|
||||
<head>
|
||||
${metas}
|
||||
<title>${title}</title>
|
||||
${links}
|
||||
</head>
|
||||
<body>
|
||||
${scripts}
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
Where `${links}` represents all `<link ..` tags for CSS and `${scripts}` represents all `<script...` tags for JavaScript files.
|
||||
|
||||
### `title`
|
||||
|
||||
Type: `String`<br>
|
||||
Default: `'Rollup Bundle'`
|
||||
|
||||
Specifies the HTML document title.
|
||||
|
||||
## Exports
|
||||
|
||||
### `makeHtmlAttributes(attributes)`
|
||||
|
||||
Parameters: `attributes`, Type: `Object`<br>
|
||||
Returns: `String`
|
||||
|
||||
Consumes an object with key-value pairs that represent an HTML element attribute name and value. The function returns all pairs as a space-separated string of valid HTML element attributes. e.g.
|
||||
|
||||
```js
|
||||
const { makeHtmlAttributes } = require('@rollup/plugin-html');
|
||||
|
||||
makeHtmlAttributes({ lang: 'en', 'data-batcave': 'secret' });
|
||||
// -> 'lang="en" data-batcave="secret"'
|
||||
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`), `iife`, and `umd` [output formats](https://rollupjs.org/guide/en/#outputformat), as those are most commonly used as browser bundles. Other formats can be used, but will require using the [`template`](#template) option to specify a custom template function which renders the unique requirements of other 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)
|
||||
|
||||
### `amd`
|
||||
## Status
|
||||
|
||||
Will likely require use of RequireJS semantics, which allows only for a single entry `<script>` tag. If more entry chunks are emitted, these need to be loaded via a proxy file. RequireJS would also need to be a dependency and added to the build: https://requirejs.org/docs/start.html.
|
||||
This plugin is in an early state. As such not everything that is supported yet, and the options may change.
|
||||
|
||||
### `system`
|
||||
### (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
|
||||
|
||||
Would require a separate `<script>` tag first that adds the `s.js` minimal loader. Loading modules might then resemble: `<script>System.import('./batman.js')</script>`.
|
||||
|
||||
## Attribution
|
||||
### 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
|
||||
- ...
|
||||
|
||||
This plugin was inspired by and is based upon [mini-html-webpack-plugin](https://github.com/styleguidist/mini-html-webpack-plugin) by Juho Vepsäläinen and Artem Sapegin, with permission.
|
||||
# Contibuting
|
||||
|
||||
## Meta
|
||||
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)
|
||||
|
||||
[CONTRIBUTING](/.github/CONTRIBUTING.md)
|
||||
|
||||
[LICENSE (MIT)](/LICENSE)
|
||||
# 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).
|
||||
|
||||
Reference in New Issue
Block a user