@modern-js/main-doc 0.0.0-nightly-20231217170625 → 0.0.0-nightly-20231219170633

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

@@ -0,0 +1,341 @@
+---
+sidebar_position: 1
+title: Usage
+---
+
+# Usage
+
+Enabling SSR is simple. Just set the value of [`server.ssr`](/configure/app/server/ssr) to `true`.
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: true,
+  },
+});
+```
+
+## SSR Data Fetch
+
+Modern.js provides a Data Loader that simplifies data fetching for developers working with SSR and CSR. Each routing module, such as `layout.tsx` and `page.tsx`, can define its own Data Loader:
+
+```ts title="src/routes/page.data.ts"
+export const loader = () => {
+  return {
+    message: 'Hello World',
+  };
+};
+```
+
+Within the component, data returned by the `loader` function can be accessed through the Hooks API:
+
+```tsx
+export default () => {
+  const data = useLoaderData();
+  return <div>{data.message}</div>;
+};
+```
+
+Modern.js breaks the traditional model of server-side rendering (SSR) development and offers users a more user-friendly SSR development experience.
+
+This feature offers elegant degradation processing. If the SSR request fails, it will automatically downgrade and restart the request on the browser side.
+
+Developers should still be mindful of data fallback, including `null` values or unexpected data returns. This will help prevent React rendering errors and messy results during SSR.
+
+:::info
+
+1. When requesting a page through client-side routing, Modern.js sends an HTTP request. The server receives the request and executes the corresponding Data Loader function for the page, then returns the execution result as a response to the browser.
+
+2. When using Data Loader, data is fetched before rendering. Modern.js also supports obtaining data during component rendering. For more related content, please refer to [Data Fetch](/guides/basic-features/data/data-fetch).
+
+:::
+
+## Keep Rendering Consistent
+
+In some businesses, it is usually necessary to make different UI displays based on the current operating container environment characteristics, such as [UA](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) information.
+
+If not handled carefully, unexpected rendering results are likely to occur.
+
+Here is an example to show the problem when SSR and CSR rendering are inconsistent, add the following code to the component:
+
+```tsx
+{
+  typeof window !== 'undefined' ? <div>browser content</div> : null;
+}
+```
+
+After launching the application and accessing the page, you will find that the browser console throws a warning message.
+
+```sh
+Warning: Expected server HTML to contain a matching <div> in <div>.
+```
+
+This is caused by React's hydration logic on the client side detecting inconsistencies between the rendered result and the SSR rendering result. Although the page appears normal, in complex applications, it is likely to cause problems such as DOM hierarchy confusion and style disorder.
+
+:::info
+More information about [`React hydrate`](https://reactjs.org/docs/react-dom.html#hydrate).
+
+:::
+
+The application needs to maintain consistency between SSR and CSR rendering results. If there is inconsistency, it means that this part of the content does not need to be rendered in SSR.
+
+Modern.js provides a [`<NoSSR>`](/apis/app/runtime/core/use-runtime-context) component for such content that does not need to be rendered in SSR.
+
+```ts
+import { NoSSR } from '@modern-js/runtime/ssr';
+```
+
+Wrap the element that does not require SSR with the `NoSSR` component:
+
+```tsx
+<NoSSR>
+  <div>client content</div>
+</NoSSR>
+```
+
+After modifying the code, refreshing the page shows that the previous warning has disappeared. Opening the Network tab of the browser devtools and checking the returned HTML document does not contain content wrapped by `NoSSR` components.
+
+:::info
+['useRuntimeContext'](/apis/app/runtime/core/use-runtime-context) can get complete request information, which can be used to ensure consistent rendering results between SSR and CSR.
+
+:::
+
+## Pay Attention to Memory Leaks
+
+:::warning
+Developers need to pay special attention to memory leaks in the SSR mode. Even tiny memory leaks can have an impact on the service after a large number of accesses.
+
+:::
+
+When using SSR, each request from the browser will trigger the server to re-execute the component rendering logic. Therefore, it is necessary to avoid defining any data structures that may continue to grow globally, subscribing to events globally, or creating streams that will not be destroyed globally.
+
+For example, when using [redux-observable](https://redux-observable.js.org/), developers who are used to CSR development usually code in the component like this:
+
+```tsx
+/* This code is for demonstration purposes only */
+import { createEpicMiddleware, combineEpics } from 'redux-observable';
+
+const epicMiddleware = createEpicMiddleware();
+const rootEpic = combineEpics();
+
+export default function Test() {
+  epicMiddleware.run(rootEpic);
+  return <div>Hello Modern.js</div>;
+}
+```
+
+Create a Middleware instance `epicMiddleware` outside the component and call epicMiddleware.run inside the component.
+
+When running on the client-side, this code will not cause any issues. However, during SSR, the Middleware instance cannot be destroyed.
+
+Every time a component is rendered and `epicMiddleware.run(rootEpic)` is called, new event bindings are added internally which causes the entire object to grow continuously and ultimately affects application performance.
+
+CSR issues are not easy to detect, so when switching from CSR to SSR, if you are unsure whether the application has such problems, you can perform stress testing on applications.
+
+## Converging Server Data.
+
+In order to maintain the data requested during the SSR phase, it can be directly used on the browser side. Modern.js will inject the data and state collected during rendering into HTML.
+
+However, in CSR applications, there are often situations where interface data is large and component states are not converged. If SSR is used directly in this case, the rendered HTML may have a problem of being too large.
+
+At this time, SSR may not only fail to improve user experience for applications but may also have an opposite effect.
+
+Therefore, when using SSR, **developers need to properly slim down the application**.
+
+1. Focus on the first screen, SSR can request only the data needed for the first screen and render the remaining parts on the browser side.
+2. Remove data unrelated to rendering from the returned data of the interface.
+
+## Serverless Pre-render
+
+:::warning
+x.43.0+ has been deprecated, Please instance of [SSR Cache](guides/advanced-features/ssr/cache).
+:::
+
+Modern.js provides the Serverless Pre-rendering (SPR) feature to improve SSR performance.
+
+SPR uses pre-rendering and caching technology to provide responsive performance for SSR pages. It enables SSR applications to have the response speed and stability of static web pages while also maintaining dynamic data updates.
+
+Using SPR in Modern.js is very simple. Just add the PreRender component to your component, and the page where it is located will automatically enable SPR.
+
+Here is a simulated component that uses the useLoaderData API. The request in the Data Loader takes 2 seconds to consume.
+
+```tsx title="page.data.ts"
+import { useLoaderData } from '@modern-js/runtime/router';
+
+export const loader = async () => {
+  await new Promise((resolve, reject) => {
+    setTimeout(() => {
+      resolve(null);
+    }, 2000);
+  });
+
+  return {
+    message: 'Hello Modern.js',
+  };
+};
+```
+
+```tsx title="page.tsx"
+import { useLoaderData } from '@modern-js/runtime/router';
+
+export default () => {
+  const data = useLoaderData();
+  return <div>{data?.message}</div>;
+};
+```
+
+After executing the `dev` command and opening the page, it is obvious that the page needs to wait 2s before returning.
+
+Use the `<PreRender>` component for optimization next, which can be directly exported from `@modern-js/runtime/ssr`.
+
+```ts
+import { PreRender } from '@modern-js/runtime/ssr';
+```
+
+Use the `<PreRender>` component within the routing component and set the parameter `interval` to indicate that the expiration time of this rendering result is 5 seconds:
+
+```tsx
+<PreRender interval={5} />
+```
+
+After modification, execute `pnpm run build && pnpm run serve` to start the application and open the page.
+
+The first time it is opened, there is no difference in rendering compared to before, and there is still a 2-second delay.
+
+Clicking refresh opens the page instantly, but at this point, the page data has not changed due to the refresh because the cache has not yet expired.
+
+After waiting for 5 seconds and refreshing the page, the data on the page remained unchanged. After refreshing again, the data changed, but the response was nearly immediate.
+
+This is because during the previous request, SPR had already asynchronously obtained a new rendering result in the background, and this time's requested page is a version that has been cached on the server.
+
+One can imagine that when the `interval` is set to 1, users can have a responsive experience of static pages while perceiving real-time data.
+
+:::info
+For more detail, see [`<PreRender>`](/apis/app/runtime/ssr/pre-render).
+
+:::
+
+## Treeshaking
+
+When SSR is enabled, Modern.js uses the same entry point to build both SSR Bundle and CSR Bundle. Therefore, errors may occur if there are Web APIs in the SSR Bundle or Node APIs in the CSR Bundle.
+
+Introducing Web APIs in components usually do some global listening or obtaining browser-related data, such as:
+
+```tsx
+document.addEventListener('load', () => {
+  console.log('document load');
+});
+const App = () => {
+  return <div>Hello World</div>;
+};
+export default App;
+```
+
+Importing Node API in component files is usually done when using `useLoader`, for example:
+
+```ts
+import fse from 'fs-extra';
+export default () => {
+  const file = fse.readFileSync('./myfile');
+  return {
+    ...
+  };
+};
+```
+
+### Use Environment Variables
+
+For the first case, we can directly use the built-in environment variable `MODERN_TARGET` in Modern.js to determine and remove unused code during build time:
+
+```ts
+if (process.env.MODERN_TARGET === 'browser') {
+  document.addEventListener('load', () => {
+    console.log('document load');
+  });
+}
+```
+
+After the development environment is bundled, the SSR and CSR artifacts will be compiled into the following content. Therefore, there will be no more Web API errors in the SSR environment.
+
+```ts
+// SSR production
+if (false) {
+}
+
+// CSR production
+if (true) {
+  document.addEventListener('load', () => {
+    console.log('document load');
+  });
+}
+```
+
+:::note
+For more information, see [environment variables](/guides/basic-features/env-vars).
+
+:::
+
+### Use File Suffix
+
+But for example, in the second case, `fs-extra` is imported in the code, which has side effects using Node API internally. If it is directly referenced in the component, it will cause an error when CSR loading.
+
+Environment variables does not work in this case. Modern.js also supports using files with the `.node.` suffix to distinguish between the packaging files of SSR Bundle and CSR Bundle products.
+
+You can create a proxy layer by creating files with the same name but different extensions, such as `.ts` and `.node.ts`:
+
+```ts title="compat.ts"
+export const readFileSync: any = () => {};
+```
+
+```ts title="compat.node.ts"
+export { readFileSync } from 'fs-extra';
+```
+
+Import `./compat` directly in the file. In SSR environment, files with `.node.ts` suffix will be used first, while in CSR environment, files with `.ts` suffix will be used.
+
+```ts title="App.tsx"
+import { readFileSync } from './compat'
+
+export const loader = () => {
+  const file = readFileSync('./myfile');
+  return {
+    ...
+  };
+};
+```
+
+### Independent File
+
+The two methods mentioned above will both bring some mental burden to developers. In real business scenarios, we found that most of the mixed Node/Web code appears in data requests.
+
+Therefore, Modern.js has designed a [Data Fetch](/guides/basic-features/data/data-fetch) to separate CSR and SSR code based on [Nested Routing](/guides/basic-features/routes).
+
+We can separate **data requests from component code** by using independent files. Write the component logic in `routes/page.tsx` and write the data request logic in `routes/page.data.ts`.
+
+```ts title="routes/page.tsx"
+export default Page = () => {
+  return <div>Hello World<div>
+}
+```
+
+```ts title="routes/page.data.tsx"
+import fse from 'fs-extra';
+export const loader = () => {
+  const file = fse.readFileSync('./myfile');
+  return {
+    ...
+  };
+}
+```
+
+## Remote Request
+
+When initiating interface requests in SSR, developers sometimes encapsulate isomorphic request tools themselves. For some interfaces that require passing user cookies, developers can use the ['useRuntimeContext'](/guides/basic-features/data/data-fetch#route-loader) API to get the request header for implementation.
+
+It should be noted that the obtained request header is for HTML requests, which may not be suitable for API requests. Therefore, ** don't passed through all request headers **.
+
+In addition, some backend interfaces or common gateways will verify based on the information in the request header. Full pass-through can easily lead to various difficult-to-troubleshoot issues, so it is recommended to **pass through as needed**.
+
+If it is really necessary to pass through all request headers, please be sure to filter the `host` field.

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

@@ -22,7 +22,7 @@ Please refer to [Modern.js Builder - Using PostCSS](https://modernjs.dev/builder
 
 ## Using CSS Modules
 
-Please read the [Using CSS Modules](https://modernjs.dev/builder/en/guide/basic/css-modules.html) section to learn about the complete usage of CSS Modules.
+Please read the [Using CSS Modules](/guides/basic-features/css-modules) section to learn about the complete usage of CSS Modules.
 
 ## Using CSS-in-JS
 
@@ -72,18 +72,7 @@ To use [Tailwind CSS](https://tailwindcss.com/) in Modern.js, you can follow the
 ? Please select the feature name: Enable Tailwind CSS
 ```
 
-After successful initialization, you will see the following additions to the `package.json` file:
-
-```json title="./package.json"
-{
-  "dependencies": {
-    "tailwindcss": "^3.0.0"
-  },
-  "devDependencies": {
-    "@modern-js/plugin-tailwindcss": "^2.0.0"
-  }
-}
-```
+After successful initialization, you will see that the `package.json` has added dependencies for `tailwindcss` and `@modern-js/plugin-tailwindcss`.
 
 2. Register the Tailwind plugin in `modern.config.ts`:
 

package/docs/en/guides/get-started/tech-stack.mdx

@@ -97,7 +97,7 @@ Modern.js supports three CSS preprocessors: [Sass](https://sass-lang.com/), [Les
 
 Modern.js provides out-of-the-box support for [CSS Modules](https://github.com/css-modules/css-modules), which is implemented internally based on [css-loader](https://www.npmjs.com/package/css-loader).
 
-Please refer to ["Use CSS Modules"](https://modernjs.dev/builder/en/guide/basic/css-modules.html) for usage instructions.
+Please refer to ["Use CSS Modules"](/guides/basic-features/css-modules) for usage instructions.
 
 ---
 

package/docs/zh/guides/advanced-features/optimize-bundle.mdx

@@ -77,7 +77,7 @@ export default {
 ```
 
 :::tip
-请阅读 [浏览器兼容性](https://modernjs.dev/builder/guide/advanced/browser-compatibility.html) 章节来了解更多关于 polyfill 的用法。
+请阅读 [浏览器兼容性](/guides/advanced-features/compatibility) 章节来了解更多关于 polyfill 的用法。
 :::
 
 ## 使用图片压缩

package/docs/zh/guides/advanced-features/ssr/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "服务端渲染",
+  "position": 3,
+  "link": {
+    "type": "doc",
+    "id": "guides/advanced-features/ssr/index"
+  }
+}

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

@@ -0,0 +1,189 @@
+---
+sidebar_position: 3
+title: 缓存
+---
+
+# 渲染缓存
+
+有时我们会将计算结果进行缓存，例如 React useMemo, useCallback Hook。
+通过缓存我们可以减少计算的次数来减少 CPU 资源占用，提高用户体验。
+
+通过将服务器端渲染（SSR）结果进行缓存能够减少服务器每次请求时的计算和渲染时间，从而加速页面加载速度，提高用户体验。
+降低服务端负载，节省计算资源，提高用户访问速度。
+
+:::info
+需要 x.43.0+
+:::
+
+## 配置方式
+
+在 `server/cache.[t|j]s` 中配置缓存即可开启缓存：
+
+```ts title="server/cache.ts"
+import type { CacheOption } from '@modern-js/runtime/server';
+
+export const cacheOption: CacheOption = {
+  maxAge: 500, // ms
+  staleWhileRevalidate: 1000, // ms
+};
+```
+
+## 配置说明
+
+### 缓存配置
+
+缓存策略参考 [stale-while-revalidate](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) 进行实现。
+
+在 `maxAge` 时间内会直接返回缓存内容，超过 `maxAge` 但在 `staleWhileRevalidate` 内也会直接返回缓存内容，但同时会异步做一次重新渲染。
+
+**Object 类型**
+
+```ts
+export interface CacheControl {
+  maxAge: number;
+
+  staleWhileRevalidate: number;
+
+  customKey?: string | ((pathname: string) => string);
+}
+```
+
+其中 customKey 为自定义缓存 key。默认情况下 Modern.js 将会把请求 pathname 作为 key 进行缓存，但在某些情况下这不能满足你的需求，开发者可以进行自定义。
+
+**Function 类型**
+
+```ts
+export type CacheOptionProvider = (
+  req: IncomingMessage,
+) => Promise<CacheControl> | CacheControl;
+```
+
+有时开发者需要通过 req 来自定义缓存 key，可以配置为函数的形式进行处理, 例如以下代码：
+
+```ts title="server/cache.ts"
+
+import type { CacheOption, CacheOptionProvider } from '@modern-js/runtime/server';
+
+const provider: CacheOptionProvider = (req) => {
+  const { url, headers, ... } = req;
+
+  const key = computedKey(url, headers, ...);
+
+  return {
+    maxAge: 500, // ms
+    staleWhileRevalidate: 1000, // ms
+    customKey: key,
+  }
+}
+
+export const cacheOption: CacheOption = provider;
+```
+
+**Mapping 类型**
+
+```ts
+export type CacheOptions = Record<string, CacheControl | CacheOptionProvider>;
+```
+
+有时开发者面对不同的路由需要应用不同的缓存策略。我们也提供一种映射的方式进行配置, 以下列代码为例子
+
+```ts title="server/cache.ts"
+import type { CacheOption } from '@modern-js/runtime/server';
+
+export const cacheOption: CacheOption = {
+  '/home': {
+    maxAge: 50,
+    staleWhileRevalidate: 100,
+  },
+  '/about': {
+    maxAge: 1000 * 60 * 60 * 24, // one day
+    staleWhileRevalidate: 1000 * 60 * 60 * 24 * 2 // two day
+  },
+  '*': (req) => { // 若上述路由无法匹配，则会匹配到 '*'
+    const { url, headers, ... } = req;
+    const key = computedKey(url, headers, ...);
+
+    return {
+      maxAge: 500,
+      staleWhileRevalidate: 1000,
+      customKey: key,
+    }
+  }
+}
+```
+
+- 路由 `http://xxx/home` 将会应用第一条规则。
+- 路由 `http://xxx/about` 将会应用第二条规则。
+- 路由 `http://xxx/abc` 将会应用最后一条规则。
+
+上述 `/home` 和 `/about` 将会作为模式进行匹配，这意味着 `/home/abc` 也会匹配上该规则。
+同时，你也可以在其中编写正则语法：`/home/.+`
+
+### 缓存容器
+
+默认情况下，Server 将会使用内存进行缓存。但通常情况下服务将会部署在 serverless 上。每一次的服务访问可能都是一个新的进程，这样每次访问都不能应用缓存
+
+故开发者也可以自定义缓存容器，容器需实现接口 `Containter`
+
+```ts
+export interface Containter<K = string, V = string> {
+  /**
+   * Returns a specified element from the containter. If the value that is associated to the provided key is an object, then you will get a reference to that object and any change made to that object will effectively modify it inside the Containter.
+   * @returns Returns the element associated with the specified key. If no element is associated with the specified key, undefined is returned.
+   */
+  get: (key: K) => Promise<V | undefined>;
+
+  /**
+   * Adds a new element with a specified key and value to the containter. If an element with the same key already exists, the element will be updated.
+   *
+   * The ttl indicates cache expiration time.
+   */
+  set: (key: K, value: V, options?: { ttl?: number }) => Promise<this>;
+
+  /**
+   * @returns boolean indicating whether an element with the specified key exists or not.
+   */
+  has: (key: K) => Promise<boolean>;
+
+  /**
+   * @returns true if an element in the containter existed and has been removed, or false if the element does not exist.
+   */
+  delete: (key: K) => Promise<boolean>;
+}
+```
+
+以下面代码为例，开发者可实现一个 redis 容器。
+
+```ts
+import type { Containter, CacheOption } from '@modern-js/runtime/server';
+
+class RedisContainter implements Containter {
+  redis = new Redis();
+
+  async get(key: string) {
+    return this.redis.get(key);
+  }
+
+  async set(key: string, value: string): Promise<this> {
+    this.redis.set(key, value);
+    return this;
+  }
+
+  async has(key: string): Promise<boolean> {
+    return this.redis.has(key);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.redis.delete(key);
+  }
+}
+
+const containter = new RedisContainter();
+
+export const customContainer: Containter = containter;
+
+export const cacheOption: CacheOption = {
+  maxAge: 500, // ms
+  staleWhileRevalidate: 1000, // ms
+};
+```

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

@@ -0,0 +1,22 @@
+# 服务端渲染
+
+通过在服务器端将网页的 HTML 内容渲染成完整的网页，然后将生成的网页发送到客户端，客户端只需要显示网页即可，不需要再进行额外的渲染。
+
+它主要的优势在于
+
+- 提高首屏加载速度：SSR 可以在服务器端生成完整的网页，客户端只需要下载网页内容即可，不需要再进行额外的渲染，从而提高了首屏加载速度。
+- 提高用户体验：SSR 可以提高网页的响应速度，从而提高用户体验。
+- 有利于 SEO：SSR 可以生成完整的 HTML 内容，搜索引擎可以直接索引 HTML 内容，从而提高网站的排名。
+
+如果你有以下场景的需求，开发者可以考虑使用 SSR 来渲染你的页面：
+
+1. 对首屏加载速度要求较高的网站，如电商网站、新闻网站等。
+2. 对用户体验要求较高的网站，如社交网站、游戏网站等。
+3. 对 SEO 要求较高的网站，如企业官网、博客等。
+
+在 Modern.js 中，SSR 也是开箱即用的。开发者无需为 SSR 编写复杂的服务端逻辑，也无需关心 SSR 的运维，或是创建单独的服务。
+除了开箱即用的 SSR 服务，为了保证开发者的开发体验，我们还具备：
+
+- 完备的 SSR 降级策略，保证页面能够安全运行。
+- 自动分割子路由，按需加载，减少首屏资源体积。
+- 内置缓存系统，解决服务端负载高的问题。