@modern-js/main-doc 2.27.0 → 2.28.0

package/CHANGELOG.md

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

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/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/package.json

@@ -15,14 +15,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.27.0",
+  "version": "2.28.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.27.0"
+    "@modern-js/builder-doc": "^2.28.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.28.0",
+    "@modern-js/doc-plugin-auto-sidebar": "2.28.0",
+    "@modern-js/doc-tools": "2.28.0"
   },
   "scripts": {
     "dev": "modern dev",