RFC-012: HTML Plugin #500

byted-meow · 2022-08-02T12:38:25Z

byted-meow
Aug 2, 2022

Feature Name: rs-html-plugin
Start Date: 2022-08-02
Rspack Issue: speedy-js/rspack#494

Summary

Html plugin for rspack, which collect emitted assets from entries and write them to a HTML file.

Motivation

It's hard to track emitted assets manually as it may contain hash. This plugin can do this automatically so that no need to change the <script src=""> each time after pack.

Guide-level explanation

It is a new plugin and should not affect the other part of rspack.

Reference-level explanation

Introduce and config this plugin

The plugin behaves like other rust inline plugins as it's currently not easy to load external rust plugin.

Introduce the plugin in rspack.config.json like this:

{
  "plugins": [
    [
      "html", 
      {
        "template": "index.html"
      }
    ]
  ]
}

This is for multi-entry support like html-webpack-plugin.

It reads both its own config (for filename, template...) and rspack config (for publicPath...) to the structure:

// the config
pub struct HtmlPluginConfig {
  // emitted file name in output path
  pub filename: String,
  // template html file
  pub template: Option<String>,
  // `auto`, `head`, `body` or None
  pub inject: Option<String>,
  // path or `auto`
  pub public_path: Option<String>,
  // `blocking`, `defer`, or `module`
  pub script_loading: Option<String>,

  // entry_chunk_name (only entry chunks are supported)
  pub chunks: Option<Vec<String>>,
  pub excluded_chunks: Option<Vec<String>>,

  // future
  pub minify: Option<bool>,
}

Retrieve the Entrypoints from compilation

After initialization, it taps into process_assets hooks to analyze assets.

retrieve each entry chunk's name for filter
get each entry's emitted assets and their path, filter out irrelevant ones (such as created by hmr)
may concat public path according to the configuration

Parse Template and Emit the Html Assets

This plugin use swc-html to parse the HTML template files(if we are about to support ejs-like template compile, it happens before this step).

For better and easy plugin system, we create a simple custom html tag structure instead of the ast provided swc-html.

As the structure provided by swc is too complicated to operate and we may need to pass it to other plugins like sub-resource integrity plugin.

// the tag
pub struct HTMLPluginTag {
  pub tag_name: String,
  pub attributes: Vec<HtmlPluginAttribute>,
  pub void_tag: bool,
  // `head`, `body` or None
  pub append_to: Option<String>,
  // future
  pub meta: (),
}

// attributes are presented as plain string.
// namespace is not supported currently.
pub struct HtmlPluginAttribute {
  pub attr_name: String,
  // None is ``
  pub attr_value: Option<String>,
}

Note only new tags created by the plugin itself are included, no items in the template are provided, which is aligned to html-webpack-plugin.

The assets got from the previous step are grouped by their type (or extensions, if type is not provided). mjs, js files are appended to end of <body> by default, and css appended to end of <head>.

After all tags are set, they are inserted to their place in swc-html's document. And use code_gen to convert it back to HTML text content.

These steps are all done in process_assets hook.

Drawbacks

It just collects all the entry assets and appends them to html template. It does not function as html is a first-class citizen.

No dependencies in the Html template are collected. If we should support something like favicon, an extra work is needed.

Rationale and alternatives

We could also implement parcel-like html plugin which treat html as first-class citizen.

Prior art

html-webpack-plugin use webpack child compilation to compile template. And it does not parse the html file, but use only regex to match meta, head and body tag.

Unresolved questions

process_assets hook and a better compilation & assets implementation are todos and will be discussed in another RFC.

Future possibilities

If this plugin wins the first-citizen one, some new features may be added to it.

EJS-like Template Compilation

As there's no ejs implementation in rust, we could use handlebars by default to compile html files.

Subresource Integrity Support

We could also inline the subresource plugin and create sha384 for entries using sha2. This is much more performant (and a bit less flexible).

Plugin System

A plugin system is the best way to add extensibility to it. For example, js plugins could be used to compile the template, and node crypto could be used to create sha384...

And others...

support html minify

an extra config minify is provided, if true, use swc-html-minifier to minify output html
support hmr, hash and cache...

hardfist · 2022-08-03T02:59:45Z

hardfist
Aug 3, 2022
Maintainer

{
  "plugins": [
    [
      "html", 
      {
        "template": "index.html"
      }
    ]
  ]
}

The Configuration is not friendly to typescript, maybe we just put it into configuraion

{
 "html": [{"template": "index.html"},{"template": "other.html"}]
}

2 replies

byted-meow Aug 3, 2022
Author

It comes to me at first time but it has some drawbacks... such as:

not able to order plugins (like webpack, I don't know if we need to do that)
it makes me think it is no a configurable plugin, but an ability

{
  abilities: {
    js: {}, // js plugin configuration
    css: {}, // css plugin configuration
    html: {}, // html plugin configuration
  }
}

so I make it a babel-like configuration...
But yes, if considering about typescript, using this structure is definitely better.

byted-meow Aug 3, 2022
Author

We can use defineHtmlPlugin({template: 'index.html', ...}) to mitigate the Typescript issue

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RFC-012: HTML Plugin #500

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 1 comment 2 replies

{{title}}

{{title}}

{{title}}

Select a reply

RFC-012: HTML Plugin #500

byted-meow Aug 2, 2022

Summary

Motivation

Guide-level explanation

Reference-level explanation

Introduce and config this plugin

Retrieve the Entrypoints from compilation

Parse Template and Emit the Html Assets

Drawbacks

Rationale and alternatives

Prior art

Unresolved questions

Future possibilities

Replies: 1 comment · 2 replies

hardfist Aug 3, 2022 Maintainer

byted-meow Aug 3, 2022 Author

byted-meow Aug 3, 2022 Author

byted-meow
Aug 2, 2022

Replies: 1 comment 2 replies

hardfist
Aug 3, 2022
Maintainer

byted-meow Aug 3, 2022
Author

byted-meow Aug 3, 2022
Author