@modern-js/main-doc 2.27.0 → 2.29.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @modern-js/main-doc
 
+## 2.29.0
+
+### Patch Changes
+
+- @modern-js/builder-doc@2.29.0
+
+## 2.28.0
+
+### Patch Changes
+
+- @modern-js/builder-doc@2.28.0
+
 ## 2.27.0
 
 ### Patch Changes

package/docs/en/configure/app/performance/dns-prefetch.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: dnsPrefetch
+---
+
+# performance.dnsPrefetch
+
+:::tip
+This config is provided by Modern.js Builder, more detail can see [performance.dnsPrefetch](https://modernjs.dev/builder/en/api/config-performance.html#performancednsprefetch).
+:::
+
+import Main from '@modern-js/builder-doc/docs/en/config/performance/dnsPrefetch.md';
+
+<Main />

package/docs/en/configure/app/performance/preconnect.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: preconnect
+---
+
+# performance.preconnect
+
+:::tip
+This config is provided by Modern.js Builder, more detail can see [performance.preconnect](https://modernjs.dev/builder/en/api/config-performance.html#performancepreconnect).
+:::
+
+import Main from '@modern-js/builder-doc/docs/en/config/performance/preconnect.md';
+
+<Main />

package/docs/en/configure/app/tools/swc.mdx

@@ -4,7 +4,7 @@ sidebar_label: swc
 
 # tools.swc
 
-- **Type:** `Object`
+- **Type:** `Object | Function`
 - **Default:** `undefined`
 
 ## Introduction
@@ -44,4 +44,19 @@ export default defineConfig({
 });
 ```
 
+Or using function to have more customize config, or to modify the default config.
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  tools: {
+    swc(config, { setConfig }) {
+      // Used for transpiling decorator of mobx correctly
+      setConfig(config, 'jsc.transform.useDefineForClassFields', true);
+    },
+  },
+});
+```
+
 For config details, please refer to [Modern.js Builder - SWC Plugin Configuration](https://modernjs.dev/builder/en/plugins/plugin-swc.html#config).

package/docs/en/guides/advanced-features/rspack-start.mdx

@@ -54,6 +54,10 @@ import { appTools, defineConfig } from '@modern-js/app-tools';
 });
 ```
 
+import RspackPrecautions from '@modern-js/builder-doc/docs/en/shared/rspackPrecautions.md';
+
+<RspackPrecautions />
+
 ## Migrating configuration
 
 After enabling Rspack building capability, further configuration migration is needed by referring to the [Configuration Differences](https://modernjs.dev/builder/en/guide/advanced/rspack-start.html#migrating-from-webpack-to-rspack).

package/docs/en/guides/advanced-features/ssr.mdx

@@ -159,10 +159,10 @@ Using SPR in Modern.js is very simple. Just add the PreRender component to your
 
 Here is a simulated component that uses the useLoaderData API. The request in the Data Loader takes 2 seconds to consume.
 
-```jsx
+```tsx title="page.loader.ts"
 import { useLoaderData } from '@modern-js/runtime/router';
 
-export const loader = async () => {
+export default async () => {
   await new Promise((resolve, reject) => {
     setTimeout(() => {
       resolve(null);
@@ -173,6 +173,10 @@ export const loader = async () => {
     message: 'Hello Modern.js',
   };
 };
+```
+
+```tsx title="page.tsx"
+import { useLoaderData } from '@modern-js/runtime/router';
 
 export default () => {
   const data = useLoaderData();

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

@@ -147,6 +147,29 @@ In summary, if there is a `layout.tsx` file under the sub-route's file directory
 
 All routes should end with the `<Page>` component. If the developer introduces the `<Outlet>` component in the `page.tsx` file, there will be no effect.
 
+#### Config
+
+Each `Layout` or `Page` file can define its own `config` file, such as `page.config.ts`. In this file, we have an conventinal on a named export called `handle`, which you can define any properties:
+
+```ts title="routes/blog/page.config.ts"
+export const handle = {
+  breadcrumbName: 'profile'
+}
+```
+
+These properties as defined are available via the [`useMatches`](https://reactrouter.com/en/main/hooks/use-matches) hook:
+
+```ts title="routes/layout.ts"
+export default () => {
+  const matches = useMatches;
+  const breadcrumbs = matches.map(matchedRoute => matchedRoute?.handle?.breadcrumbName);
+  return (
+    <Breadcrumb names={breadcrumbs}>
+    </Breadcrumb>
+  )
+}
+```
+
 ### Dynamic Routing
 
 Routes generated from file directories named with `[]` will be handled as dynamic routes. For example, the following file directory:
@@ -204,7 +227,18 @@ For example, the following directory structure:
     └── page.tsx
 ```
 
-When accessing any path that does not match, the `routes/$.tsx` component will be rendered. Similarly, you can use [useParams](/apis/app/runtime/router/router#useparams) in `$.tsx` to capture the remaining parts of the URL.
+When accessing any path that does not match(For example `/blog/a`), the `routes/$.tsx` component will be rendered, because there is `layout.tsx` here, the rendered UI is as follows.
+```tsx
+<RootLayout>
+  <BlogLayout>
+    <$></$>
+  </BlogLayout>
+</RootLayout>
+```
+
+If you want access to `/blog` to also match the `blog/$.tsx` file, you need to delete the `blog/layout.tsx` file in the same directory and make sure that there are no other subroutes under `blog`.
+
+As same, you can use [useParams](/apis/app/runtime/router/router#useparams) in `$.tsx` to capture the remaining parts of the URL.
 
 ```ts title="$.tsx"
 import { useParams } from '@modern-js/runtime/router';

package/docs/en/guides/troubleshooting/dependencies.mdx

@@ -108,3 +108,16 @@ In most cases, peer dependencies warnings will not affect the project operation
 - If you are still using React 16, you will not be able to use Modern.js's runtime or server-side capabilities. You can consider using the build mode of Modern.js, that is, only using Modern.js's build capabilities. In this case, React 16 can still be used.
 
 In future major versions of Modern.js, we will gradually remove support for React 16 and React 17. Therefore, please upgrade to React 18 or higher as soon as possible.
+
+---
+
+### Type error in Modern.js configuration file?
+
+```bash
+Type 'CliPlugin<{}, {}, {}, {}>' is not assignable to type 'CliPlugin<any, {}, {}, {}>'.
+  Types of property 'setup' are incompatible.
+```
+
+When you use the Modern.js framework, the above error occurs in the configuration file, it may be due to the inconsistent versions of Modern.js related packages。You can upgrade and unify the version of modern.js related packages through `npx modern upgrade` command.
+
+In the monorepo, the above error may also occur due to inconsistent versions of the Modern.js framework used by different sub-projects.

package/docs/zh/configure/app/performance/dns-prefetch.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: dnsPrefetch
+---
+
+# performance.dnsPrefetch
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [performance.dnsPrefetch](https://modernjs.dev/builder/api/config-performance.html#performancednsprefetch)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/performance/dnsPrefetch.md';
+
+<Main />

package/docs/zh/configure/app/performance/preconnect.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: preconnect
+---
+
+# performance.preconnect
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [performance.preconnect](https://modernjs.dev/builder/api/config-performance.html#performancepreconnect)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/performance/preconnect.md';
+
+<Main />

package/docs/zh/configure/app/tools/swc.mdx

@@ -4,7 +4,7 @@ sidebar_label: swc
 
 # tools.swc
 
-- **类型：** `Object`
+- **类型：** `Object | Function`
 - **默认值：** `undefined`
 
 ## 介绍
@@ -44,4 +44,19 @@ export default defineConfig({
 });
 ```
 
+当然也可以使用函数进行更灵活的配置，或者修改某些默认配置。
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  tools: {
+    swc(config, { setConfig }) {
+      // 用于 mobx 中 decorator 编译
+      setConfig(config, 'jsc.transform.useDefineForClassFields', true);
+    },
+  },
+});
+```
+
 完整配置项请参考 [Modern.js Builder - SWC 插件配置](https://modernjs.dev/builder/plugins/plugin-swc.html#%E9%85%8D%E7%BD%AE)。

package/docs/zh/guides/advanced-features/rspack-start.mdx

@@ -55,6 +55,10 @@ import { appTools, defineConfig } from '@modern-js/app-tools';
 });
 ```
 
+import RspackPrecautions from '@modern-js/builder-doc/docs/zh/shared/rspackPrecautions.md';
+
+<RspackPrecautions />
+
 ## 配置迁移
 
 开启 Rspack 构建能力后，还需要参考 [配置差异](https://modernjs.dev/builder/guide/advanced/rspack-start.html#从-webpack-迁移到-rspack) 进行进一步的配置迁移。

package/docs/zh/guides/advanced-features/ssr.mdx

@@ -149,8 +149,6 @@ SPR 利用预渲染与缓存技术，为 SSR 页面提供静态 Web 的响应性
 这里模拟一个使用 `useLoaderData` API 的组件，Data Loader 中的请求需要消耗 2s 时间。
 
 ```tsx title="page.loader.ts"
-import { useLoaderData } from '@modern-js/runtime/router';
-
 export default async () => {
   await new Promise((resolve, reject) => {
     setTimeout(() => {
@@ -165,6 +163,8 @@ export default async () => {
 ```
 
 ```tsx title="page.tsx"
+import { useLoaderData } from '@modern-js/runtime/router';
+
 export default () => {
   const data = useLoaderData();
   return <div>{data?.message}</div>;

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

@@ -150,6 +150,31 @@ export default () => {
 
 所有的路由，理论上都应该由 `<Page>` 组件结束。在 `page.tsx` 文件内，如果开发者引入 `<Outlet>` 组件，不会有任何效果。
 
+#### Config
+
+每个 `Layout` 或 `Page` 文件都可以定义一个自己的 `config` 文件，如 `page.config.ts`，该文件中我们约定了一个具名导出 `handle`，
+这个字段中你可以定义任意属性：
+
+```ts title="routes/page.config.ts"
+export const handle = {
+  breadcrumbName: 'profile'
+}
+```
+
+定义的这些属性可以通过 [`useMatches`](https://reactrouter.com/en/main/hooks/use-matches) hook 获取：
+
+```ts title="routes/layout.ts"
+export default () => {
+  const matches = useMatches;
+  const breadcrumbs = matches.map(matchedRoute => matchedRoute?.handle?.breadcrumbName);
+  return (
+    <Breadcrumb names={breadcrumbs}>
+    </Breadcrumb>
+  )
+}
+```
+
+
 ### 动态路由
 
 通过 `[]` 命名的文件目录，生成的路由会作为动态路由。例如以下文件目录：
@@ -201,13 +226,25 @@ export default () => {
 
 ```bash
 └── routes
-    ├── $.tsx
     ├── blog
-    │   └── page.tsx
+    │   ├── $.tsx
+    │   └── layout.tsx
+    └── layout.tsx
     └── page.tsx
 ```
 
-当访问任何匹配不到的路径时，都会渲染 `routes/$.tsx` 组件，同样，`$.tsx` 中可以使用 [useParams](/apis/app/runtime/router/router#useparams) 捕获 url 的剩余部分。
+当访问任何匹配不到的路径时(如 `/blog/a`)，都会渲染 `routes/$.tsx` 组件，因为这里有 `layout.tsx`，渲染的 UI 如下：
+```tsx
+<RootLayout>
+  <BlogLayout>
+    <$></$>
+  </BlogLayout>
+</RootLayout>
+```
+
+如果希望访问 `/blog` 时，也匹配到 `blog/$.tsx` 文件，需要删除同目录下的 `blog/layout.tsx` 文件，同时保证 `blog` 下面没有其他子路由。
+
+同样，`$.tsx` 中可以使用 [useParams](/apis/app/runtime/router/router#useparams) 捕获 url 的剩余部分。
 
 ```ts title="$.tsx"
 import { useParams } from '@modern-js/runtime/router';
@@ -216,7 +253,8 @@ const params = useParams();
 params['*']; // => 'aaa/bbb'
 ```
 
-`$.tsx` 可以加入到 `routes` 目录下的任意目录中，一个常见的使用示例是添加 `routes/$.tsx` 文件去定制任意层级的 404 页面。
+`$.tsx` 可以加入到 `routes` 目录下的任意目录中，一个常见的使用示例是添加 `routes/$.tsx` 文件去定制任意层级的 404 内容。
+
 
 ### 无路径布局
 

package/docs/zh/guides/troubleshooting/dependencies.mdx

@@ -108,3 +108,16 @@ Type '{}' is not assignable to type 'ReactNode'.
 - 如果你仍然在使用 React 16，那么将无法使用 Modern.js 的运行时或服务端能力。你可以考虑使用 Modern.js 的构建模式，即只使用 Modern.js 的构建能力，这种情况可以继续使用 React 16。
 
 在 Modern.js 未来的 major 版本中，我们会逐步移除对 React 16 和 React 17 的支持。因此，请尽快升级到 React 18 以上版本。
+
+---
+
+### Modern.js 配置出现类型错误？
+
+```bash
+Type 'CliPlugin<{}, {}, {}, {}>' is not assignable to type 'CliPlugin<any, {}, {}, {}>'.
+  Types of property 'setup' are incompatible.
+```
+
+当你在使用 Modern.js 框架时配置文件出现以上报错，可能是由于 Modern.js 相关包的版本号未统一导致。可以通过 `npx modern upgrade` 命令对 modern.js 依赖进行升级和版本统一。
+
+在 monorepo 中由于不同子项目所用的 Modern.js 框架版本不一致也可能出现以上问题。

package/package.json

@@ -15,14 +15,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.27.0",
+  "version": "2.29.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.27.0"
+    "@modern-js/builder-doc": "^2.29.0"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -34,9 +34,9 @@
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.27.0",
-    "@modern-js/doc-tools": "2.27.0",
-    "@modern-js/doc-plugin-auto-sidebar": "2.27.0"
+    "@modern-js/builder-doc": "2.29.0",
+    "@modern-js/doc-tools": "2.29.0",
+    "@modern-js/doc-plugin-auto-sidebar": "2.29.0"
   },
   "scripts": {
     "dev": "modern dev",