web-infra-dev · chenjiahan · Aug 23, 2024 · Aug 22, 2024 · Aug 22, 2024 · Aug 23, 2024
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -80,7 +80,7 @@ swc_html            = { version = "=0.148.0" }
 swc_html_minifier   = { version = "=0.145.0", default-features = false }
 swc_node_comments   = { version = "=0.24.0" }
 
-
+rspack_dojang = { version = "0.1.8" }
 [workspace.metadata.release]
 rate-limit = { existing-packages = 70, new-packages = 70 }
 [profile.dev]

diff --git a/crates/node_binding/binding.d.ts b/crates/node_binding/binding.d.ts
@@ -1830,3 +1830,4 @@ export interface ThreadsafeNodeFS {
   mkdirp: (name: string) => Promise<string | void> | string | void
   removeDirAll: (name: string) => Promise<string | void> | string | void
 }
+
diff --git a/crates/rspack_plugin_html/Cargo.toml b/crates/rspack_plugin_html/Cargo.toml
@@ -17,7 +17,7 @@ rayon             = { workspace = true }
 regex             = { workspace = true }
 rspack_base64     = { version = "0.1.0", path = "../rspack_base64" }
 rspack_core       = { version = "0.1.0", path = "../rspack_core" }
-rspack_dojang     = "0.1.7"
+rspack_dojang     = { workspace = true }
 rspack_error      = { version = "0.1.0", path = "../rspack_error" }
 rspack_hook       = { version = "0.1.0", path = "../rspack_hook" }
 rspack_paths      = { version = "0.1.0", path = "../rspack_paths" }

diff --git a/crates/rspack_plugin_html/src/plugin.rs b/crates/rspack_plugin_html/src/plugin.rs
@@ -13,7 +13,7 @@ use rspack_core::{
   rspack_sources::{RawSource, SourceExt},
   Compilation, CompilationAsset, CompilationProcessAssets, FilenameTemplate, PathData, Plugin,
 };
-use rspack_dojang::dojang::Dojang;
+use rspack_dojang::dojang::{Dojang, DojangOptions};
 use rspack_error::{miette, AnyhowError, Diagnostic, Result};
 use rspack_hook::{plugin, plugin_hook};
 use rspack_paths::AssertUtf8;
@@ -102,7 +102,13 @@ async fn process_assets(&self, compilation: &mut Compilation) -> Result<()> {
 
   // process with template parameters
   let mut dj = Dojang::new();
-  dj.add(url.clone(), content.clone())
+  // align escape | unescape with lodash.template syntax https://lodash.com/docs/4.17.15#template which is html-webpack-plugin's default behavior
+  dj.with_options(DojangOptions {
+    escape: "-".to_string(),
+    unescape: "=".to_string(),
+  });
+
+  dj.add_with_option(url.clone(), content.clone())
     .expect("failed to add template");
   let mut template_result =
     match dj.render(&url, serde_json::json!(&self.config.template_parameters)) {

diff --git a/tests/plugin-test/html-plugin/basic.test.js b/tests/plugin-test/html-plugin/basic.test.js
@@ -3782,7 +3782,28 @@ describe("HtmlWebpackPlugin", () => {
       done,
     );
   });
-
+  it('syntax-support', (done) => {
+    testHtmlPlugin(
+        {
+          entry: {},
+          output: {
+            path: OUTPUT_DIR,
+            filename: "index_bundle.js",
+            assetModuleFilename: "assets/demo[ext]",
+          },
+          plugins: [new HtmlWebpackPlugin(
+            {
+              minify:false,
+              templateContent: '<%= myHtml %><%- myHtml %>',
+              templateParameters: {
+                 "myHtml": "<span>Rspack</span>"
+              }
+            })]
+        },
+        [`
+<html>
+<head></head><body><span>Rspack</span>&lt;span&gt;Rspack&lt;/span&gt;</body></html>`], null, done);
+  });
   // TODO: html-webpack-plugin loader
   // it("allows to set custom loader interpolation settings", (done) => {
   //   testHtmlPlugin(

diff --git a/website/docs/en/plugins/rspack/html-rspack-plugin.mdx b/website/docs/en/plugins/rspack/html-rspack-plugin.mdx
@@ -27,8 +27,64 @@ If its options do not meet your needs, you can also directly use the community [
 
 :::warning
 `rspack.HtmlRspackPlugin` does not support the full `ejs` syntax; it only supports a subset of the `ejs` syntax. If you need full `ejs` syntax support, you can use `html-webpack-plugin` directly.
+In order to align the default template syntax of `html-webpack-plugin`, Rspack changed the default EJS escape and unescape to be the same as `html-webpack-plugin`'s default syntax.
 :::
 
+### Supported EJS Syntax
+
+Only the following basic interpolation expressions are supported. Here, the interpolation expressions only support the most basic string types and do not support arbitrary JavaScript expressions. Other EJS syntaxes are currently not supported.
+
+#### \<%-: Escaped output
+
+Escapes the content within the interpolation:
+
+```html title="ejs"
+<p>Hello, <%- name %>.</p>
+<p>Hello, <%- 'the Most Honorable ' + name %>.</p>
+```
+
+```json title="locals"
+{
+  "name": "Rspack<y>"
+}
+```
+
+```html title="html"
+<p>Hello, Rspack&lt;y&gt;.</p>
+<p>Hello, the Most Honorable Rspack&lt;y&gt;.</p>
+```
+
+#### \<%=: Unescaped output
+
+Does not escape the content within the interpolation:
+
+```html title="ejs"
+<p>Hello, <%- myHtml %>.</p>
+<p>Hello, <%= myHtml %>.</p>
+
+<p>Hello, <%- myMaliciousHtml %>.</p>
+<p>Hello, <%= myMaliciousHtml %>.</p>
+```
+
+```json title="locals"
+{
+  "myHtml": "<strong>Rspack</strong>",
+  "myMaliciousHtml": "</p><script>document.write()</script><p>"
+}
+```
+
+```html title="html"
+<p>Hello, &lt;strong&gt;Rspack&lt;/strong&gt;.</p>
+<p>Hello, <strong>Rspack</strong>.</p>
+
+<p>Hello, &lt;/p&gt;&lt;script&gt;document.write()&lt;/script&gt;&lt;p&gt;.</p>
+<p>Hello,</p>
+<script>
+  document.write();
+</script>
+<p>.</p>
+```
+
 ## Usage
 
 The plugin will generate an HTML file for you that includes all your JS outputs in the head using `<script>` tags.

diff --git a/website/docs/zh/plugins/rspack/html-rspack-plugin.mdx b/website/docs/zh/plugins/rspack/html-rspack-plugin.mdx
@@ -26,9 +26,65 @@ new rspack.HtmlRspackPlugin(options);
 如果它提供的配置项无法满足你的需求，你也可以直接使用社区的 [html-webpack-plugin](https://www.npmjs.com/package/html-webpack-plugin) 插件。
 
 :::warning
-`rspack.HtmlRspackPlugin` 不支持完整的 `ejs` 语法, 仅支持 `ejs` 语法的一个子集，如果对完整的 `ejs` 语法支持有需求，可以直接使用 `html-webpack-plugin`。
+`rspack.HtmlRspackPlugin` 不支持完整的 EJS 语法, 仅支持 EJS 语法的一个子集，如果你对完整的 EJS 语法支持有需求，可以直接使用 `html-webpack-plugin`。为了和 `html-webpack-plugin` 的默认的插值语法对齐，
+Rspack 修改了 EJS 的 escape 和 unescape 的默认语法，使其采用和 `html-webpack-plugin` 相同的语法。
 :::
 
+### 支持的 EJS 语法
+
+仅支持如下基本的插值表达式,这里的插值表达式只支持最基本的字符串类型，不支持任意的 JavaScript 表达式，其他的 `ejs` 语法目前均不支持。
+
+#### \<%-: Escaped output
+
+对插值内容进行 escape：
+
+```html title="ejs"
+<p>Hello, <%- name %>.</p>
+<p>Hello, <%- 'the Most Honorable ' + name %>.</p>
+```
+
+```json title="locals"
+{
+  "name": "Rspack<y>"
+}
+```
+
+```html title="html"
+<p>Hello, Rspack&lt;y&gt;.</p>
+<p>Hello, the Most Honorable Rspack&lt;y&gt;.</p>
+```
+
+#### \<%=: Unescaped output
+
+不对插值内容进行 escape：
+
+```html title="ejs"
+<p>Hello, <%- myHtml %>.</p>
+<p>Hello, <%= myHtml %>.</p>
+
+<p>Hello, <%- myMaliciousHtml %>.</p>
+<p>Hello, <%= myMaliciousHtml %>.</p>
+```
+
+```json title="locals"
+{
+  "myHtml": "<strong>Rspack</strong>",
+  "myMaliciousHtml": "</p><script>document.write()</script><p>"
+}
+```
+
+```html title="html"
+<p>Hello, &lt;strong&gt;Rspack&lt;/strong&gt;.</p>
+<p>Hello, <strong>Rspack</strong>.</p>
+
+<p>Hello, &lt;/p&gt;&lt;script&gt;document.write()&lt;/script&gt;&lt;p&gt;.</p>
+<p>Hello,</p>
+<script>
+  document.write();
+</script>
+<p>.</p>
+```
+
 ## 用法
 
 这个插件会为你生成一个 HTML 文件，该文件的 head 包含了所有 JS 产物对应的 `<script>` 标签。