@modern-js/main-doc 2.26.0 → 2.28.0

package/docs/en/tutorials/first-app/c03-css.mdx

@@ -1,9 +1,10 @@
 ---
 title: Add Style
 ---
+
 # Add Style
 
-import { Tabs, Tab as TabItem } from "@theme";
+import { Tabs, Tab as TabItem } from '@theme';
 
 In the previous chapter, we learned how to use components from the third-party library.
 
@@ -15,7 +16,7 @@ First of all, we want to control the display of contact avatars by ourselves, an
 
 ![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c03-css-expect.jpg)
 
-Hypothesis has no ready-made components to implement, so you need to write some CSS yourself. Here we use [styled-components] (https://styled-components.com/) to implement similar requirements. Modern.js out of the box supports styled-components, which requires neither dependency nor configuration.
+Hypothesis has no ready-made components to implement, so you need to write some CSS yourself. Here we use [styled-components](https://styled-components.com/) to implement similar requirements. Modern.js out of the box supports styled-components, which requires neither dependency nor configuration.
 
 Style-components avoids many problems of traditional CSS writing through modularization. For example, writing styles directly on the style attribute of elements, the visual details of UI will also be mixed with the details of UI structure and business logic. Or classname needs to avoid global space renaming, which requires the use of naming conventions.
 

package/docs/zh/configure/app/experiments/source-build.mdx

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

package/docs/zh/configure/app/source/alias-strategy.mdx

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

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

@@ -4,7 +4,7 @@ sidebar_label: swc
 
 # tools.swc
 
-- **类型：** `Object`
+- **类型：** `Object | Function`
 - **默认值：** `undefined`
 
 ## 介绍
@@ -21,7 +21,7 @@ import SWC from '@modern-js/builder-doc/docs/zh/shared/swc.md';
 
 ## 安装
 
-import EnableSWC from '@modern-js/builder-doc/docs/zh/shared/enable-swc.md';
+import EnableSWC from '@modern-js/builder-doc/docs/zh/shared/enableSwc.md';
 
 <EnableSWC />
 
@@ -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

@@ -5,7 +5,7 @@ sidebar_position: 1
 
 # 使用 Rspack
 
-import Rspack from '@modern-js/builder-doc/docs/zh/shared/rspack-tip.mdx';
+import Rspack from '@modern-js/builder-doc/docs/zh/shared/rspackTip.mdx';
 
 <Rspack />
 
@@ -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 内容。
+
 
 ### 无路径布局