@modern-js/main-doc 2.65.3 → 2.65.5

package/docs/en/apis/app/commands.mdx

@@ -78,6 +78,7 @@ Usage: modern build [options]
 Options:
   -c --config <config>  specify the configuration file, which can be a relative or absolute path
   -h, --help            show command help
+  -w --watch            turn on watch mode, watch for changes and rebuild
   --analyze             analyze the bundle and view size of each module
 ```
 

package/docs/en/apis/app/hooks/config/_meta.json

@@ -0,0 +1 @@
+["html", "favicon", "icon", "mock", "public", "upload"]

package/docs/en/apis/app/hooks/config/favicon.mdx

@@ -0,0 +1,29 @@
+---
+title: favicon.*
+sidebar_position: 3
+---
+
+# Favicon
+
+When there is a `favicon.*` file in the `config` directory at the root of the project, Modern.js will automatically set the file to the [html.favicon](/configure/app/html/favicon) configuration option for generating the favicon icon on the page:
+
+```
+./config
+└── favicon.ico
+```
+
+After the build is completed, you can see the following tags automatically generated in HTML:
+
+```html
+<link rel="icon" href="/favicon.ico" />
+```
+
+## Order
+
+When setting up the favicon, Modern.js looks for files in the following order:
+
+- `favicon.png`
+- `favicon.jpg`
+- `favicon.jpeg`
+- `favicon.svg`
+- `favicon.ico`

package/docs/en/apis/app/hooks/config/icon.mdx

@@ -1,36 +1,9 @@
 ---
-title: icon/
+title: icon.*
 sidebar_position: 2
 ---
 
-# icon/
-
-## Favicon
-
-When there is a `favicon.*` file in the `config` directory at the root of the project, Modern.js will automatically set the file to the [html.favicon](/configure/app/html/favicon) configuration option for generating the favicon icon on the page:
-
-```
-./config
-└── favicon.ico
-```
-
-After the build is completed, you can see the following tags automatically generated in HTML:
-
-```html
-<link rel="icon" href="/favicon.ico" />
-```
-
-### Order
-
-When setting up the favicon, Modern.js looks for files in the following order:
-
-- `favicon.png`
-- `favicon.jpg`
-- `favicon.jpeg`
-- `favicon.svg`
-- `favicon.ico`
-
-## Apple Touch Icon
+# Apple Touch Icon
 
 When there is an `icon.*` file in the `config` directory at the root of the project, Modern.js will automatically set the file to the [html.appIcon](/configure/app/html/app-icon) configuration option for generating the Apple Touch Icon icon under the iOS system.
 
@@ -45,7 +18,7 @@ After the build is completed, you can see the following tags automatically gener
 <link rel="apple-touch-icon" sizes="180x180" href="/static/image/icon.png" />
 ```
 
-### Order
+## Order
 
 When setting up the app icon, Modern.js looks for files in the following order:
 

package/docs/en/guides/basic-features/html.mdx

@@ -24,10 +24,14 @@ For example, consider the following directory structure:
     └── modern-app-env.d.ts
 ```
 
-`entry-a` will use the `Docoument.[jt]sx` file under the current entry as the template. If there is no `Document.[jt]sx` file under the current entry, like `entry-b`, it will look for the `Document.[jt]sx` file under the root directory.
+`entry-a` will use the `Document.[jt]sx` file under the current entry as the template. If there is no `Document.[jt]sx` file under the current entry, like `entry-b`, it will look for the `Document.[jt]sx` file under the root directory.
 
 If not found, default template will be used.
 
+:::tip
+The `Document.[jt]sx` module will be compiled by esbuild and rendered to a string as the HTML template content, similar to [Static Site Generation](/guides/basic-features/render/ssg.html). The HTML template module will not be compiled by the Bundler. The React Hooks in the component also will not be executed at browser runtime, and JavaScript resources such as images cannot be resolved and imported.
+:::
+
 ### HTML Components
 
 Modern.js provides some components for rendering pages to help developers generate templates. These components can be used from `@modern-js/runtime/document`:

package/docs/en/guides/basic-features/routes.mdx

@@ -530,7 +530,11 @@ This feature is very useful when applications require pre-rendered data, custom
 ```ts title="src/routes/layout.tsx"
 import { RuntimeContext } from '@modern-js/runtime';
 
-export const init = (context: RuntimeContext) => {
+type InitialData = {
+  message: string;
+}
+
+export const init = (context: RuntimeContext): InitialData => {
   return {
     message: 'Hello World',
   };
@@ -542,7 +546,7 @@ import { useRuntimeContext } from '@modern-js/runtime;
 
 export default () => {
   const context = useRuntimeContext();
-  const { message } = context.initialData;
+  const { message } = context.initialData as InitialData;
 
   return <div>{message}</div>;
 };
@@ -551,9 +555,9 @@ export default () => {
 With SSR, the browser can obtain the data returned by `init` during SSR. Developers can decide whether to re-fetch the data on the browser side to override the SSR data. For example:
 
 ```tsx title="src/routes/layout.tsx"
-import { RuntimeContext } from '@modern-js/runtime;
+import type { RuntimeContext } from '@modern-js/runtime;
 
-export const init = (context: RuntimeContext) => {
+export const init = (runtimeContext: RuntimeContext) => {
   if (process.env.MODERN_TARGET === 'node') {
     return {
       message: 'Hello World By Server',

package/docs/en/guides/topic-detail/module-federation/application.mdx

@@ -46,7 +46,10 @@ import { createModuleFederationConfig } from '@module-federation/modern-js';
 
 export default createModuleFederationConfig({
   name: 'remote',
-  filename: 'remoteEntry.js',
+  manifest: {
+    filePath:'static',
+  },
+  filename: 'static/remoteEntry.js',
   exposes: {
     './app': './src/export-App.tsx',
   },
@@ -109,4 +112,4 @@ You can refer to the example here: [Modern.js & Module Federation Application-Le
 
 ## Related Documentation
 
-- [Module Federation Bridge](https://module-federation.io/zh/practice/bridge/index.html)
+- [Module Federation Bridge](https://module-federation.io/zh/practice/bridge/index.html)

package/docs/en/guides/topic-detail/module-federation/usage.mdx

@@ -54,7 +54,10 @@ import { createModuleFederationConfig } from '@module-federation/modern-js';
 
 export default createModuleFederationConfig({
   name: 'remote',
-  filename: 'remoteEntry.js',
+  manifest: {
+    filePath: 'static',
+  },
+  filename: 'static/remoteEntry.js',
   exposes: {
     './Button': './src/components/Button.tsx',
   },
@@ -65,6 +68,10 @@ export default createModuleFederationConfig({
 });
 ```
 
+:::tip
+In the above code block, we have prefixed both the manifest and remoteEntry.js exported by Module Federation with `static`. This is because Modern.js requires all resources that need to be exposed to be placed in the `static/` directory, and Modern.js's server will only host the `static/` directory in production environments.
+:::
+
 Additionally, modify `modern.config.ts` to provide a development environment port for the producer, allowing the consumer to access the producer's resources through this port:
 
 ```ts title="modern.config.ts"
@@ -99,7 +106,7 @@ import { createModuleFederationConfig } from '@module-federation/modern-js';
 export default createModuleFederationConfig({
   name: 'host',
   remotes: {
-    remote: 'remote@http://localhost:3051/mf-manifest.json',
+    remote: 'remote@http://localhost:3051/static/mf-manifest.json',
   },
   shared: {
     react: { singleton: true },
@@ -173,8 +180,45 @@ After modifying the producer's code, the consumer will automatically fetch the p
 
 Access `http://localhost:8080/remote`, and you will see that the page includes the `Button` component from the producer's remote module.
 
+We can also execute `modern serve` locally to simulate the production environment.
+
+Because the Module Federation plugin will automatically read Modern.js's `output.assetPrefix` configuration as the access address for remote modules, and this value defaults to `/` after building in the production environment.
+
+If we want to simulate the production environment in local, but not configure `output.assetPrefix`, consumers will pull the entry file of the remote module from their own domain. So We can add the following configuration:
+
+```ts
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { moduleFederationPlugin } from '@module-federation/modern-js';
+
+const isLocal = process.env.IS_LOCAL === 'true';
+
+// https://modernjs.dev/en/configure/app/usage
+export default defineConfig({
+  server: {
+    port: 3051,
+  },
+  runtime: {
+    router: true,
+  },
+  output: {
+    // Now this configuration is only used in the local when you run modern serve command.
+    // If you want to deploy the application to the platform, use your own domain name.
+    // Module federation will automatically write it to mf-manifest.json, which influences consumer to fetch remoteEntry.js.
+    assetPrefix: isLocal ? 'http://127.0.0.1:3051' : '/',
+  },
+  plugins: [
+    appTools({
+      bundler: 'rspack', // Set to 'webpack' to enable webpack
+    }),
+    moduleFederationPlugin(),
+  ],
+});
+```
+
+Now, in the producer, run `IS_LOCAL=true modern build && modern serve`, and in the consumer, run `modern build && modern serve` to simulate the production environment locally and access the remote modules.
+
 You can refer to this example: [Modern.js & Module Federation Basic Example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/module-federation/base).
 
 ## Related Documentation
 
-- [Module Federation Official Documentation](https://module-federation.io/zh/guide/framework/modernjs.html)
+- [Module Federation Official Documentation](https://module-federation.io/zh/guide/framework/modernjs.html)

package/docs/zh/apis/app/commands.mdx

@@ -78,6 +78,7 @@ Usage: modern build [options]
 Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
   -h, --help  显示命令帮助
+  -w --watch  开启 watch 模式, 监听文件变更并重新构建
   --analyze   分析构建产物体积，查看各个模块打包后的大小
 ```
 

package/docs/zh/apis/app/hooks/config/_meta.json

@@ -0,0 +1 @@
+["html", "favicon", "icon", "mock", "public", "upload"]

package/docs/zh/apis/app/hooks/config/favicon.mdx

@@ -0,0 +1,29 @@
+---
+title: favicon.*
+sidebar_position: 3
+---
+
+# Favicon
+
+当项目根目录的 `config` 目录下存在 `favicon.*` 文件时，Modern.js 会自动将该文件设置到 [html.favicon](/configure/app/html/favicon) 配置项中，用于生成页面的 favicon 图标：
+
+```
+./config
+└── favicon.ico
+```
+
+构建完成后，可以看到 HTML 中自动生成了以下标签：
+
+```html
+<link rel="icon" href="/favicon.ico" />
+```
+
+## 查找顺序
+
+在设置 app icon 时，Modern.js 会按以下顺序寻找文件：
+
+- `favicon.png`
+- `favicon.jpg`
+- `favicon.jpeg`
+- `favicon.svg`
+- `favicon.ico`

package/docs/zh/apis/app/hooks/config/icon.mdx

@@ -1,36 +1,9 @@
 ---
-title: icon/
+title: icon.*
 sidebar_position: 2
 ---
 
-# icon/
-
-## Favicon
-
-当项目根目录的 `config` 目录下存在 `favicon.*` 文件时，Modern.js 会自动将该文件设置到 [html.favicon](/configure/app/html/favicon) 配置项中，用于生成页面的 favicon 图标：
-
-```
-./config
-└── favicon.ico
-```
-
-构建完成后，可以看到 HTML 中自动生成了以下标签：
-
-```html
-<link rel="icon" href="/favicon.ico" />
-```
-
-### 查找顺序
-
-在设置 app icon 时，Modern.js 会按以下顺序寻找文件：
-
-- `favicon.png`
-- `favicon.jpg`
-- `favicon.jpeg`
-- `favicon.svg`
-- `favicon.ico`
-
-## Apple Touch Icon
+# Apple Touch Icon
 
 当项目根目录的 `config` 目录下存在 `icon.*` 文件时，Modern.js 会自动将该文件设置到 [html.appIcon](/configure/app/html/app-icon) 配置项中，用于生成 iOS 系统下的 Apple Touch Icon 图标。
 
@@ -45,7 +18,7 @@ sidebar_position: 2
 <link rel="apple-touch-icon" sizes="180x180" href="/static/image/icon.png" />
 ```
 
-### 查找顺序
+## 查找顺序
 
 在设置 app icon 时，Modern.js 会按以下顺序寻找文件：
 

package/docs/zh/guides/basic-features/html.mdx

@@ -25,10 +25,14 @@ Modern.js 约定，在 `src/` 或入口目录下，可以创建 `Document.[jt]sx
     └── modern-app-env.d.ts
 ```
 
-`entry-a` 会优先使用当前入口下的 `Docoument.[jt]sx` 文件。如果当前入口没有 `Document.[jt]sx` 文件，例如 `entry-b`，则会查找根目录下的 `Document.[jt]sx` 文件。
+`entry-a` 会优先使用当前入口下的 `Document.[jt]sx` 文件。如果当前入口没有 `Document.[jt]sx` 文件，例如 `entry-b`，则会查找根目录下的 `Document.[jt]sx` 文件。
 
 如果未找到，将会使用 Modern.js 的默认模板。
 
+:::tip
+`Document.[jt]sx` 模块将会被使用 esbuild 编译为 Node.js 产物、并在编译时以 `renderToStaticMarkup` 渲染为字符串以作为 HTML 模板的内容，其行为类似[静态站点生成](/guides/basic-features/render/ssg.html)。HTML 模板模块不会经过 Bundler 编译打包，因此组件中的 React Hooks 不会在浏览器运行时被执行，也不支持导入 JavaScript 以外的图片等资源模块。
+:::
+
 ### HTML 组件
 
 Modern.js 提供了一些列渲染页面的组件，用来帮助开发者生成模板，可以从 `@modern-js/runtime/document` 中使用这些组件：

package/docs/zh/guides/basic-features/routes.mdx

@@ -533,7 +533,11 @@ export const init = (context: RuntimeContext) => {
 ```ts title="src/routes/layout.tsx"
 import { RuntimeContext } from '@modern-js/runtime';
 
-export const init = (context: RuntimeContext) => {
+type InitialData = {
+  message: string;
+}
+
+export const init = (context: RuntimeContext): InitialData => {
   return {
     message: 'Hello World',
   };
@@ -545,7 +549,7 @@ import { useRuntimeContext } from '@modern-js/runtime';
 
 export default () => {
   const context = useRuntimeContext();
-  const { message } = context.initialData;
+  const { message } = context.initialData as InitialData;
 
   return <div>{message}</div>;
 };
@@ -554,9 +558,9 @@ export default () => {
 配合 SSR 功能时，浏览器端可以获取到 SSR 时 `init` 返回的数据，开发者可以自行判断是否要在浏览器端重新获取数据来覆盖 SSR 数据，例如：
 
 ```tsx title="src/routes/layout.tsx"
-import { RuntimeContext } from '@modern-js/runtime';
+import type { RuntimeContext } from '@modern-js/runtime';
 
-export const init = (context: RuntimeContext) => {
+export const init = (runtimeContext: RuntimeContext) => {
   if (process.env.MODERN_TARGET === 'node') {
     return {
       message: 'Hello World By Server',

package/docs/zh/guides/topic-detail/module-federation/application.mdx

@@ -46,7 +46,10 @@ import { createModuleFederationConfig } from '@module-federation/modern-js';
 
 export default createModuleFederationConfig({
   name: 'remote',
-  filename: 'remoteEntry.js',
+  manifest: {
+    filePath:'static',
+  },
+  filename: 'static/remoteEntry.js',
   exposes: {
     './app': './src/export-App.tsx',
   },
@@ -109,4 +112,4 @@ export default RemoteApp;
 
 ## 相关文档
 
-- [Module Federation Bridge](https://module-federation.io/zh/practice/bridge/index.html)
+- [Module Federation Bridge](https://module-federation.io/zh/practice/bridge/index.html)

package/docs/zh/guides/topic-detail/module-federation/usage.mdx

@@ -55,7 +55,10 @@ import { createModuleFederationConfig } from '@module-federation/modern-js';
 
 export default createModuleFederationConfig({
   name: 'remote',
-  filename: 'remoteEntry.js',
+  manifest: {
+    filePath: 'static',
+  },
+  filename: 'static/remoteEntry.js',
   exposes: {
     './Button': './src/components/Button.tsx',
   },
@@ -66,6 +69,10 @@ export default createModuleFederationConfig({
 });
 ```
 
+:::tip
+在上述代码块中，我们为 Module Federation 导出的 manifest 和 remoteEntry.js 都设置了 `static` 前缀，这是因为 Modern.js 要求将所有需要暴露的资源都放在 `static/` 目录下，Modern.js 的服务器在生产环境时也只会托管 `static/` 目录。
+:::
+
 另外，我们还需要修改 `modern.config.ts`，为生产者提供一个开发环境的端口，让消费者可以通过此端口访问生产者的资源：
 
 ```ts title="modern.config.ts"
@@ -100,7 +107,7 @@ import { createModuleFederationConfig } from '@module-federation/modern-js';
 export default createModuleFederationConfig({
   name: 'host',
   remotes: {
-    remote: 'remote@http://localhost:3051/mf-manifest.json',
+    remote: 'remote@http://localhost:3051/static/mf-manifest.json',
   },
   shared: {
     react: { singleton: true },
@@ -142,7 +149,7 @@ export default Index;
     }
   }
 }
-``` 
+```
 
 :::tip
 在消费者中，我们通过 `remote/Button` 来引用远程模块。这里简单介绍下这个路径具体代表了什么，可以先将它抽象成 `[remoteAlias]/[remoteExpose]`。
@@ -174,8 +181,43 @@ export default Index;
 
 访问 `http://localhost:8080/remote`，可以看到页面中已经包含了生产者的远程模块 `Button` 组件。
 
+我们也可以在本地执行 `modern serve` 来模拟生产环境。
+
+因为 Module Federation 插件会自动读取 Modern.js 的 `output.assetPrefix` 配置作为远程模块的访问地址，而该值在生产环境下构建后默认是 `/`。如果不做特殊处理，消费者将从自己的域名下拉取远程模块的入口文件。我们可以添加如下配置：
+
+```ts
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { moduleFederationPlugin } from '@module-federation/modern-js';
+
+const isLocal = process.env.IS_LOCAL === 'true';
+
+// https://modernjs.dev/en/configure/app/usage
+export default defineConfig({
+  server: {
+    port: 3051,
+  },
+  runtime: {
+    router: true,
+  },
+  output: {
+    // Now this configuration is only used in the local when you run modern serve command.
+    // If you want to deploy the application to the platform, use your own domain name.
+    // Module federation will automatically write it to mf-manifest.json, which influences consumer to fetch remoteEntry.js.
+    assetPrefix: isLocal ? 'http://127.0.0.1:3051' : '/',
+  },
+  plugins: [
+    appTools({
+      bundler: 'rspack', // Set to 'webpack' to enable webpack
+    }),
+    moduleFederationPlugin(),
+  ],
+});
+```
+
+现在，在生产者中运行 `IS_LOCAL=true modern build && modern serve`，在消费者中运行 `modern build && modern serve`，即可在本地模拟生产环境，访问到远程模块。
+
 上述用例可以参考：[Modern.js & Module Federation 基础用法示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/module-federation/base)。
 
 ## 相关文档
 
-- [Module Federation 官方文档](https://module-federation.io/zh/guide/framework/modernjs.html)
+- [Module Federation 官方文档](https://module-federation.io/zh/guide/framework/modernjs.html)

package/package.json

@@ -15,14 +15,13 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.65.3",
+  "version": "2.65.5",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
-    "access": "public",
-    "provenance": true
+    "access": "public"
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "2.65.3"
+    "@modern-js/sandpack-react": "2.65.5"
   },
   "devDependencies": {
     "@rspress/shared": "1.42.0",