web-infra-dev · clChenLiang · Apr 19, 2023 · Apr 19, 2023 · Apr 19, 2023 · Apr 19, 2023
diff --git a/.changeset/healthy-timers-sin.md b/.changeset/healthy-timers-sin.md
@@ -0,0 +1,6 @@
+---
+'@modern-js/runtime': patch
+---
+
+feat: support Comment component in Document.tsx
+feat: 支持 Comment 组件,可以保留用户的注释到最终的 html 上
diff --git a/packages/document/main-doc/docs/zh/guides/basic-features/html.mdx b/packages/document/main-doc/docs/zh/guides/basic-features/html.mdx
@@ -49,6 +49,8 @@ import { Html, Body, Root, Head, Scripts } from '@modern-js/runtime/document';
 
 - `Scripts`：构建产生的 script 内容，可用于调整构建产物的位置，默认放在 `<Head>` 组件中。
 
+- `Comment`：将用户编写的 `<!-- gateway -->` 这种注释，保留输出到最新渲染的 html 中。
+
 ### 模板参数
 
 因为是 JSX 形式，`Document.[jt]sx` 里，可以比较自由的在组件内使用各种变量去赋值给各种自定义组件。
@@ -69,8 +71,8 @@ import {
   Root,
   Head,
   Body,
-  Scripts,
   DocumentContext,
+  Comment,
 } from '@modern-js/runtime/document';
 
 export default function Document(): React.ReactElement {
@@ -84,7 +86,8 @@ export default function Document(): React.ReactElement {
   return (
     <Html>
       <Head>
-        <link href="https://modernjs.dev">Modern.js</link>
+        <link href="https://modernjs.dev" />
+        <Comment>{'<!-- Need a Comment -->'}</Comment>
       </Head>
       <Body>
         <Root rootId="root">
@@ -105,49 +108,43 @@ export default function Document(): React.ReactElement {
 ```html
 <!DOCTYPE html>
 <html>
-  <head>
-    <meta charset="utf-8" />
-    <meta
-      name="viewport"
-      content="width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
-    />
-    <meta http-equiv="x-ua-compatible" content="ie=edge" />
-    <meta name="renderer" content="webkit" />
-    <meta name="layoutmode" content="standard" />
-    <meta name="imagemode" content="force" />
-    <meta name="wap-font-scale" content="no" />
-    <meta name="format-detection" content="telephone=no" />
-    <script>
-      ...
-    </script>
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport"
+        content="width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">
+    <meta http-equiv="x-ua-compatible" content="ie=edge">
+    <meta name="renderer" content="webkit">
+    <meta name="layoutmode" content="standard">
+    <meta name="imagemode" content="force">
+    <meta name="wap-font-scale" content="no">
+    <meta name="format-detection" content="telephone=no">
+    <link rel="icon" href="/a.icon">
+    <script defer src="/static/js/builder-runtime.js"></script>
     <script defer src="/static/js/lib-react.js"></script>
     <script defer src="/static/js/lib-polyfill.js"></script>
     <script defer src="/static/js/lib-router.js"></script>
-    <script
-      defer
-      src="/static/js/vendors-node_modules_pnpm_loadable_component_5_15_2_react_18_2_0_node_modules_loadable_compon-3fb0cf.js"
-    ></script>
-    <script
-      defer
-      src="/static/js/packages_runtime_plugin-router-legacy_dist_js_treeshaking_runtime_index_js-packages_runtime_p-28f4c9.js"
-    ></script>
+    <script xxx>
     <script defer src="/static/js/sub.js"></script>
-    <link href="https://www.baidu.com" />
-  </head>
+    <link href="https://modernjs.dev" />
+    <!-- Need a Comment -->
+</head>
 
-  <body>
+<body>
     <div id="root">
-      {/* <?- html ?> */}
-      <h1 style="color:red">以下为构建时传过来的参数：</h1>
-      <h2>entryName：sub</h2>
-      <h2>title：</h2>
-      <h2>rootId: root</h2>
+        <!--<?- html ?>-->
+        <h1 style="color:red">以下为构建时传过来的参数：</h1>
+        <h2> entryName：sub</h2>
+        <h2> title：</h2>
+        <h2> rootId: root</h2>
     </div>
     <h1>bottom</h1>
-    {/* <?- chunksMap.js ?> */}
-    {/* <?- SSRDataScript ?> */}
-  </body>
+    <!--<?- chunksMap.js ?>-->
+    <!--<?- SSRDataScript ?>-->
+</body>
+
 </html>
+
 ```
 
 ## Html 语法

diff --git a/packages/runtime/plugin-runtime/src/document/Comment.tsx b/packages/runtime/plugin-runtime/src/document/Comment.tsx
@@ -0,0 +1,18 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import React from 'react';
+import {
+  DOCUMENT_COMMENT_PLACEHOLDER_START,
+  DOCUMENT_COMMENT_PLACEHOLDER_END,
+} from './constants';
+
+export function Comment(props: { comment?: string; children?: string }) {
+  const { comment, children } = props;
+  const commentStr = encodeURIComponent(children || comment || '');
+  return (
+    <>
+      {`${DOCUMENT_COMMENT_PLACEHOLDER_START}`}
+      {`${commentStr}`}
+      {`${DOCUMENT_COMMENT_PLACEHOLDER_END}`}
+    </>
+  );
+}
diff --git a/packages/runtime/plugin-runtime/src/document/cli/index.ts b/packages/runtime/plugin-runtime/src/document/cli/index.ts
@@ -22,6 +22,8 @@ import {
   DOCUMENT_SCRIPT_PLACEHOLDER_START,
   DOCUMENT_SCRIPT_PLACEHOLDER_END,
   HTML_SEPARATOR,
+  DOCUMENT_COMMENT_PLACEHOLDER_START,
+  DOCUMENT_COMMENT_PLACEHOLDER_END,
 } from '../constants';
 
 const debug = createDebugger('html_genarate');
@@ -208,6 +210,19 @@ export default (): CliPlugin<AppTools> => ({
             (_scriptStr, $1) => `<script>${decodeURIComponent($1)}</script>`,
           );
         }
+        // if the Document.tsx has a comment component, replace and convert it
+        if (
+          html.includes(DOCUMENT_COMMENT_PLACEHOLDER_START) &&
+          html.includes(DOCUMENT_COMMENT_PLACEHOLDER_END)
+        ) {
+          html = html.replaceAll(
+            new RegExp(
+              `${DOCUMENT_COMMENT_PLACEHOLDER_START}(.*?)${DOCUMENT_COMMENT_PLACEHOLDER_END}`,
+              'g',
+            ),
+            (_scriptStr, $1) => `${decodeURIComponent($1)}`,
+          );
+        }
 
         // replace the html placeholder while transfer string to jsx component is not a easy way
         const finalHtml = `<!DOCTYPE html>${html}`

diff --git a/packages/runtime/plugin-runtime/src/document/constants.ts b/packages/runtime/plugin-runtime/src/document/constants.ts
@@ -28,6 +28,12 @@ export const DOCUMENT_SCRIPT_PLACEHOLDER_START = encodeURIComponent(
 export const DOCUMENT_SCRIPT_PLACEHOLDER_END = encodeURIComponent(
   '<!-- script-end -->',
 );
+export const DOCUMENT_COMMENT_PLACEHOLDER_START = encodeURIComponent(
+  '<!-- comment-start -->',
+);
+export const DOCUMENT_COMMENT_PLACEHOLDER_END = encodeURIComponent(
+  '<!-- comment-end -->',
+);
 
 export const PLACEHOLDER_REPLACER_MAP = {
   [DOCUMENT_NO_SCRIPTE_PLACEHOLDER]: `We're sorry but react app doesn't work properly without JavaScript enabled. Please enable it to continue.`,

diff --git a/packages/runtime/plugin-runtime/src/document/index.ts b/packages/runtime/plugin-runtime/src/document/index.ts
@@ -5,6 +5,7 @@ export * from './Head';
 export * from './Body';
 export * from './Root';
 export * from './Links';
+export * from './Comment';
 export * from './Scripts';
 export * from './Script';
 export * from './constants';
diff --git a/tests/integration/app-document/src/sub/Document.tsx b/tests/integration/app-document/src/sub/Document.tsx
@@ -5,6 +5,7 @@ import {
   Head,
   DocumentContext,
   Body,
+  Comment,
 } from '@modern-js/runtime/document';
 
 export default function Document(): React.ReactElement {
@@ -18,6 +19,12 @@ export default function Document(): React.ReactElement {
   return (
     <Html {...{ fromUserDoc: true }}>
       <Head>
+        {/* comment should be render to html by Comment.children */}
+        <Comment comment="<!== COMMENT BY APP but inline ==>">
+          {'<!-- COMMENT BY APP -->'}
+        </Comment>
+        {/* comment should be render to html by Comment.comment */}
+        <Comment comment="<!== COMMENT BY APP in inline ==>" />
         <link href="/ababad"></link>
         <script
           dangerouslySetInnerHTML={{

diff --git a/tests/integration/app-document/tests/index.test.js b/tests/integration/app-document/tests/index.test.js
@@ -88,18 +88,35 @@ describe('test build', () => {
     expect(existsSync('html/test/index.html')).toBe(true);
     expect(existsSync('html/sub/index.html')).toBe(true);
   });
+
   it('should have the test html and the correct content', async () => {
     const htmlNoDoc = fs.readFileSync(
       path.join(appDir, 'dist', 'html/test/index.html'),
       'utf-8',
     );
     expect(htmlNoDoc.includes('<div id="root"><!--<?- html ?>--></div>'));
   });
+
   it('should have the sub html and the correct content', async () => {
     const htmlWithDoc = fs.readFileSync(
       path.join(appDir, 'dist', 'html/sub/index.html'),
       'utf-8',
     );
     expect(htmlWithDoc.includes('<div id="root"><!--<?- html ?>--><h1'));
   });
+
+  it('should has comment in Head', async () => {
+    const htmlWithDoc = fs.readFileSync(
+      path.join(appDir, 'dist', 'html/sub/index.html'),
+      'utf-8',
+    );
+
+    expect(htmlWithDoc.includes('<!-- COMMENT BY APP -->')).toBe(true);
+    expect(htmlWithDoc.includes('<!== COMMENT BY APP in inline ==>')).toBe(
+      true,
+    );
+    expect(htmlWithDoc.includes('<!== COMMENT BY APP but inline ==>')).toBe(
+      false,
+    );
+  });
 });