@modern-js/main-doc 2.1.0 → 2.2.0

package/zh/guides/basic-features/data-fetch.mdx

@@ -0,0 +1,386 @@
+---
+title: 数据获取
+sidebar_position: 3
+---
+# 数据获取
+
+Modern.js 中提供了开箱即用的数据获取能力，开发者可以通过这些 API，在 CSR 和 SSR 环境同构的进行开发。
+
+需要注意的是，这些 API 并不帮助应用发起请求，而是帮助开发者更好地管理数据，提升项目的性能。
+
+## Data Loader(推荐)
+
+Modern.js 推荐使用约定式路由做路由的管理，通过 Modern.js 的[约定式（嵌套）路由](/guides/basic-features/routes#约定式路由)，每个路由组件(`layout.ts` 或 `page.ts`)可以有一个同名的 `loader` 文件，该 `loader` 文件需要导出一个函数，函数会在组件渲染之前执行，为路由组件提供数据。
+
+:::info
+Modern.js v1 支持通过 [useLoader](#useloader旧版) 获取数据，这已经不是我们推荐的用法，除迁移过程外，不推荐两者混用。
+
+:::
+
+### 基础示例
+
+路由组件如 `layout.ts` 或 `page.ts`，可以定义同名的 `loader` 文件，`loader` 文件中导出一个函数，该函数提供组件所需的数据，然后在路由组件中通过 `useLoaderData` 函数获取数据，如下面示例：
+
+```
+.
+└── routes
+    ├── layout.tsx
+    └── user
+        ├── layout.tsx
+        ├── layout.loader.ts
+        ├── page.tsx
+        └── page.loader.ts
+```
+
+在文件中定义以下代码：
+
+```ts title="routes/user/page.tsx"
+import { useLoaderData } from '@modern-js/runtime/router';
+import type { ProfileData } from './page.loader.ts';
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+```
+
+```ts title="routes/user/page.loader.ts"
+export type ProfileData = {
+  /*  some types */
+};
+
+export default async (): Promise<ProfileData> => {
+  const res = await fetch('https://api/user/profile');
+  return await res.json();
+};
+```
+
+:::caution
+这里路由组件和 `loader` 文件共享类型，要使用 `import type` 语法。
+
+:::
+
+在 CSR 环境下，`loader` 函数会在客户端执行，`loader` 函数内可以使用浏览器的 API（但通常不需要，也不推荐）。
+
+在 SSR 环境下，不管是首屏，还是在客户端的导航，`loader` 函数只会在服务端执行，这里可以调用任意的 Node.js API，同时这里使用的任何依赖和代码都不会包含在客户端的 bundle 中。
+
+:::info
+在以后的版本中，Modern.js 可能会支持在 CSR 环境下，`loader` 函数也在服务端运行，以提高性能和安全性，所以这里建议尽可能地保证 loader 的纯粹，只做数据获取的场景。
+
+:::
+
+当在客户端导航时，基于 Modern.js 的[约定式路由](/guides/basic-features/routes)，所有的 loader 函数会并行执行（请求），即当访问 `/user/profile` 时，`/user` 和 `/user/profile` 下的 loader 函数都会并行执行（请求），以提高客户端的性能。
+
+### `loader` 函数
+
+`loader` 函数有两个入参：
+
+#### `Params`
+
+当路由文件通过 `[]` 时，会作为[动态路由](/guides/basic-features/routes#动态路由)，动态路由片段会作为参数传入 loader 函数：
+
+```tsx
+// routes/user/[id]/page.loader.ts
+import { LoaderArgs } from '@modern-js/runtime/router';
+
+export default async ({ params }: LoaderArgs) => {
+  const { id } = params;
+  const res = await fetch(`https://api/user/${id}`);
+  return res.json();
+};
+```
+
+当访问 `/user/123` 时，`loader` 函数的参数为 `{ params: { id: '123' } }`。
+
+#### `request`
+
+`request` 是一个 [Fetch Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) 实例。
+
+一个常见的使用场景是通过 `request` 获取查询参数：
+
+```tsx
+// routes/user/[id]/page.loader.ts
+import { LoaderArgs } from '@modern-js/runtime/router';
+
+export default async ({ request }: LoaderArgs) => {
+  const url = new URL(request.url);
+  const userId = url.searchParams.get('id');
+  return queryUser(userId);
+};
+```
+
+#### 返回值
+
+`loader` 函数的返回值可以是任何可序列化的内容，也可以是一个 [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) 实例：
+
+```tsx
+const loader = async (): Promise<ProfileData> => {
+  return {
+    message: 'hello world',
+  };
+};
+export default loader;
+```
+
+默认情况下，`loader` 返回的响应 `Content-type` 是 `application/json`，`status` 为 200，你可以通过自定义 `Response` 来设置：
+
+```tsx
+const loader = async (): Promise<ProfileData> => {
+  const data = { message: 'hello world' };
+  return new Response(JSON.stringify(data), {
+    status: 200,
+    headers: {
+      'Content-Type': 'application/json; utf-8',
+    },
+  });
+};
+```
+
+### 请求 API
+
+Modern.js 对 `fetch` API 做了 polyfill, 用于发起请求，该 API 与浏览器的 `fetch` API 一致，但是在服务端也能使用该 API 发起请求，这意味着不管是 CSR 还是 SSR，都可以使用统一的 `fetch` API 进行数据获取：
+
+```tsx
+async function loader() {
+  const res = await fetch('https://api/user/profile');
+}
+```
+
+### 错误处理
+
+在 `loader` 函数中，可以通过 `throw error` 或者 `throw response` 的方式处理错误，当 `loader` 函数中有错误被抛出时，Modern.js 会停止执行当前 loader 中的代码，并将前端 UI 切换到定义的 [`ErrorBoundary`](/guides/basic-features/routes#错误处理) 组件：
+
+```tsx
+// routes/user/profile/page.loader.ts
+export default async function loader() {
+  const res = await fetch('https://api/user/profile');
+  if (!res.ok) {
+    throw res;
+  }
+  return res.json();
+}
+
+// routes/user/profile/error.tsx
+import { useRouteError } from '@modern-js/runtime/router';
+const ErrorBoundary = () => {
+  const error = useRouteError() as Response;
+  return (
+    <div>
+      <h1>{error.status}</h1>
+      <h2>{error.statusText}</h2>
+    </div>
+  );
+};
+
+export default ErrorBoundary;
+```
+
+### 获取上层组件的数据
+
+很多场景下，子组件需要获取到祖先组件 loader 中的数据，你可以通过 `useRouteLoaderData` 方便地获取到祖先组件的数据：
+
+```tsx
+// routes/user/profile/page.tsx
+import { useRouteLoaderData } from '@modern-js/runtime/router';
+
+export default function UserLayout() {
+  // 获取 routes/user/layout.loader.ts 中 loader 返回的数据
+  const data = useRouteLoaderData('user/layout');
+  return (
+    <div>
+      <h1>{data.name}</h1>
+      <h2>{data.age}</h2>
+    </div>
+  );
+}
+```
+
+`userRouteLoaderData` 接受一个参数 `routeId`，在使用约定式路由时，Modern.js 会为你自动生成`routeId`，`routeId` 的值是对应组件相对于 `src/routes` 的路径，如上面的例子中，子组件想要获取 `routes/user/layout.tsx` 中 loader 返回的数据，`routeId` 的值就是 `user/layout`。
+
+在多 entry（MPA） 场景下，`routeId` 的值需要加上对应 entry 的 name，entry name 非指定情况下一般是 entry 目录名，如以下目录结构：
+
+```bash
+.
+└── src
+    ├── entry1
+    │     └── routes
+    │           └── layout.tsx
+    └── entry2
+          └── routes
+                └── layout.tsx
+```
+
+如果想获取 `entry1/routes/layout.tsx` 中 loader 返回的数据，`routeId` 的值就是 `entry1_layout`。
+
+### (WIP)Loading UI
+
+:::info
+此功能目前是实验性质，后续 API 可能有调整。
+目前仅支持 CSR，敬请期待 Streaming SSR。
+
+:::
+
+在 `user/layout.tsx` 中添加以下代码：
+
+```tsx title="routes/user/layout.tsx"
+import {
+  Await,
+  defer,
+  useLoaderData,
+  Outlet
+} from '@modern-js/runtime/router';
+
+export const loader = () => {
+  return defer({
+    // fetchUserInfo 是一个异步函数，返回用户信息
+    userInfo: fetchUserInfo(),
+  })
+}
+
+export default function UserLayout() {
+  const { userInfo } = useLoaderData() as {userInfo: Promise<UserInfo>};
+  return (
+    <div>
+      <React.Suspense
+        fallback={<p>Loading...</p>}
+      >
+        <Await resolve={userInfo} children={userInfo => (
+          <div>
+            <span>{userInfo.name}</span>
+            <span>{userInfo.age}</span>
+            <Outlet>
+          </div>
+        )}>
+        </Await>
+      </React.Suspense>
+    </div>
+  );
+}
+```
+
+:::info
+Await 组件的具体用法请查看 [Await](https://reactrouter.com/en/main/components/await)
+
+defer 的具体用法请查看 [defer](https://reactrouter.com/en/main/guides/deferred)
+
+:::
+
+{/* TODO 缓存相关  */}
+
+### 错误用法
+
+1. `loader` 中只能返回可序列化的数据，在 SSR 环境下，`loader` 函数的返回值会被序列化为 JSON 字符串，然后在客户端被反序列化为对象。因此，`loader` 函数中不能返回不可序列化的数据（如函数）。
+
+:::warning
+目前 CSR 下没有这个限制，但我们强烈推荐你遵循该限制，且未来我们可能在 CSR 下也加上该限制。
+
+:::
+
+```ts
+// This won't work!
+export default () => {
+  return {
+    user: {},
+    method: () => {},
+  };
+};
+```
+
+2. Modern.js 会帮你调用 `loader` 函数，你不应该自己调用 `loader` 函数：
+
+```ts
+// This won't work!
+export default async () => {
+  const res = fetch('https://api/user/profile');
+  return res.json();
+};
+
+import loader from './page.loader.ts';
+export default function RouteComp() {
+  const data = loader();
+}
+```
+
+3. 不能从路由组件中引入 `loader` 文件，也不能从 `loader` 文件引入路由组件中的变量，如果需要共享类型的话，应该使用 `import type`
+
+```ts
+// Not allowed
+// routes/layout.tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+import { ProfileData } from './page.loader.ts'; // should use "import type" instead
+
+export const fetch = wrapFetch(fetch);
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+
+// routes/layout.loader.ts
+import { fetch } from './layout.tsx'; // should not be imported from the routing component
+export type ProfileData = {
+  /*  some types */
+};
+
+export default async (): Promise<ProfileData> => {
+  const res = await fetch('https://api/user/profile');
+  return await res.json();
+};
+```
+
+4. 在服务端运行时，`loader` 函数会被打包为一个统一的 bundle，所以我们不推荐服务端的代码使用 `__filename` 和 `__dirname`。
+
+## useLoader（旧版）
+
+**`useLoader`** 是 Modern.js 老版本中的 API。该 API 是一个 React Hook，专门提供给 SSR 应用使用，让开发者能同构的在组件中获取数据。
+
+:::tip
+CSR 的项目没有必要使用 `useLoader` 获取数据。
+
+:::
+
+以下是一个最简单的例子：
+
+```tsx
+import { useLoader } from '@modern-js/runtime';
+
+export default () => {
+  const { data } = useLoader(async () => {
+    console.log('fetch in useLoader');
+
+    // 这里没有发送真实的请求，只是返回了一个写死的数据。
+    // 真实项目中，应该返回从远端获取的数据。
+    return {
+      name: 'Modern.js',
+    };
+  });
+
+  return <div>Hello, {data?.name}</div>;
+};
+```
+
+上述代码启动后，访问页面。可以看到在终端输出了日志，而在浏览器终端却没有打印日志。
+
+这是因为 Modern.js 在服务端渲染时，在会收集 `useLoader` 返回的数据，并将数据注入到响应的 HTML 中。如果 SSR 渲染成功，在 HTML 中可以看到如下代码片段：
+
+```html
+<script>
+  window._SSR_DATA = {};
+</script>
+```
+
+在这全局变量中，记录了每一份数据，而在浏览器端渲染的过程中，会优先使用这份数据。如果数据不存在，则会重新执行 `useLoader` 函数。
+
+:::note
+在构建阶段，Modern.js 会自动为每个 `useLoader` 生成一个 Loader ID，并注入到 SSR 和 CSR 的 JS Bundle 中，用来关联 Loader 和数据。
+
+:::
+
+相比于 Next.js 中的 `getServerSideProps`，在渲染前预先获取数据。使用 `useLoader`，可以在组件中获取局部 UI 所需要的数据，而不用将数据层层传递。同样，也不会因为不同路由需要不同数据请求，而在最外层的数据获取函数中添加冗余的逻辑。当然 `useLoader` 也存在一些问题，例如服务端代码 Treeshaking 困难，服务端需要多一次预渲染等。
+
+Modern.js 在新版本中，设计了全新的 Loader 方案。新方案解决了这些问题，并能够配合**嵌套路由**，对页面性能做优化。
+
+:::note
+详细 API 可以查看 [useLoader](/apis/app/runtime/core/use-loader)。
+
+:::

package/zh/guides/basic-features/env-vars.mdx

@@ -0,0 +1,168 @@
+---
+title: 环境变量
+sidebar_position: 7
+---
+# 环境变量
+
+Modern.js 提供了对环境变量的支持，包含内置的环境变量和自定义的环境变量。
+
+## 内置的环境变量
+
+### NODE_ENV
+
+表示当前的执行环境，是**只读的**的环境变量，其值在不同的执行命令下具有不同的值：
+
+- `production`：执行 `modern build`、`modern serve` 命令时的默认值。
+- `test`：执行 `modern test` 命令时的默认值。
+- `development`：执行 `modern dev` 命令时的默认值，同时也是其他所有情况下的默认值。
+
+### MODERN_ENV
+
+手动设置当前的执行环境。除了上述 NODE_ENV 对应的值之外，这里支持自定义环境名称，例如 `staging`、`boe` 等。
+
+:::tip
+MODERN_ENV 的优先级高于 NODE_ENV。
+
+:::
+
+### MODERN_TARGET
+
+使用 `@modern-js/runtime` 时会自动注入，用于区分 SSR 与 CSR 环境。开发者可以自行在代码中判断，构建时会默认移除 dead code。
+
+```ts title="App.tsx"
+function App() {
+  if (process.env.MODERN_TARGET === 'browser') {
+    console.log(window.innerHeight);
+  }
+}
+```
+
+开发环境打包后，可以看到 SSR 产物和 CSR 产物如下：
+
+```js title="dist/bundles/main.js"
+function App() {
+  if (false) {
+  }
+}
+```
+
+```js title="dist/static/main.js"
+function App() {
+  if (true) {
+    console.log(window.innerHeight);
+  }
+}
+```
+
+:::note
+在生产环境，会将 dead code 移除，例如上述 `if` 语句。
+
+:::
+
+这种方式可以针对不同客户端提供不同的产物，保证代码体积最小化。也能方便处理不同环境下，代码中的一些副作用，
+
+## 自定义环境变量
+
+环境变量支持通过 `shell` 和 `.env` 文件两种方式指定。
+
+### 通过 `shell` 指定
+
+在命令前添加自定义环境变量：
+
+```shell
+REACT_APP_FOO=123 BAR=456 pnpm run dev
+```
+
+### 通过 `.env` 文件指定
+
+在项目根目录创建 `.env` 文件，并添加自定义环境变量，这些环境变量会默认添加到启动项目的 Node.js 进程中，例如：
+
+```bash
+REACT_APP_FOO=123
+BAR=456
+```
+
+`.env` 文件遵循以下规则加载规则：
+
+- `.env`：默认加载。
+- `.env.{ MODERN_ENV | NODE_ENV }`：针对具体环境设置环境变量，会覆盖 `.env` 中的设置。
+
+当需要根据环境使用不同的配置时，可以把环境变量定义到对应环境名称的 `.env` 文件中，并在启动项目时手动设置执行环境。例如使用以下命令启动项目时，将会加载 `.env` 和 `.env.staging`:
+
+```shell
+MODERN_ENV=staging pnpm run dev
+```
+
+## 使用环境变量
+
+### 约定命名
+
+在前端代码中可以直接使用 `NODE_ENV` 环境变量。另外，以 `MODERN_` 开头的自定义环境变量，也可以在代码中直接使用。
+
+例如:
+
+```js
+if (process.env.NODE_ENV === 'development') {
+  // do something
+}
+```
+
+执行 `pnpm run dev` 命令之后可以看到如下构建产物：
+
+```js
+if (true) {
+  // do something
+}
+```
+
+同样在自定义的 HTML 模板中，也可以直接使用这类环境变量。如 `config/html/head.html`:
+
+```js
+<meta name="test" content="<process.env.NODE_ENV>">
+```
+
+### 任意命名
+
+如果需要在代码中使用任意名称的环境变量，可以在 [`source.globalVars`](/configure/app/source/global-vars) 配置指定, 例如：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    globalVars: {
+      'process.env.VERSION': process.env.VERSION,
+    }.
+  },
+});
+```
+
+此时，在代码中的 `process.env.VERSION`，将会被替换为环境变量中 `VERSION` 的值。
+
+:::note
+`source.globalVars` 也支持将其他表达式或字符串替换为指定的值，不仅限于环境变量。
+
+:::
+
+## 使用全局替换
+
+除了环境变量，Modern.js 也支持将代码中的变量替换成其它值或者表达式，可以用于在代码逻辑中区分开发环境与生产环境等场景。
+
+例如将代码中的 `TWO` 转换为 `1 + 1` 的表达式：
+
+```ts
+export default {
+  source: {
+    define: {
+      TWO: '1 + 1',
+    },
+  },
+};
+```
+
+```ts
+const foo = TWO;
+
+// ⬇️ Turn into being...
+const foo = 1 + 1;
+```
+
+在大多数情况下，`source.globalVars` 已经能满足替换变量的需求。但 `source.globalVars` 传入的值都会默认被 JSON 序列化，因此无法做出像上面例子中 `1 + 1` 的替换，此时就需要使用 [`source.define`](/configure/app/source/define)。