@modern-js/app-tools 3.7.0 → 3.8.1

package/docs/guides/basic-features/render/ssr.md

@@ -0,0 +1,321 @@
+# Server-Side Rendering
+
+Server-Side Rendering (SSR) generates complete HTML pages on the server and sends them to the browser for direct display, without requiring additional client-side rendering.
+
+## Core Advantages
+
+- **Faster First Screen**: Server-side pre-rendering allows the browser to display content directly without waiting for JavaScript execution
+- **Better SEO**: Search engines can directly index complete HTML content
+- **Out of the Box**: No need to write complex server-side logic or maintain separate services
+
+:::info Default Rendering Mode
+Modern.js SSR **uses streaming rendering (Streaming SSR) by default**, allowing pages to be returned progressively as they render, so users can see initial content faster.
+
+For detailed usage, refer to the [Streaming SSR](/guides/basic-features/render/streaming-ssr.md) documentation.
+
+To switch to traditional SSR mode (waiting for all data to load before returning at once), you can configure:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: {
+      mode: 'string', // Traditional SSR mode
+    },
+  },
+});
+```
+
+:::
+
+## Enabling SSR
+
+Enabling SSR in Modern.js is straightforward. Simply set [`server.ssr`](/configure/app/server/ssr.md) to `true`:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: true, // Streaming rendering enabled by default
+  },
+});
+```
+
+## Data Fetching
+
+Modern.js provides Data Loader, enabling developers to fetch data isomorphically under both SSR and CSR. Each route module (such as `layout.tsx` and `page.tsx`) can define its own Data Loader:
+
+:::tip Learn More
+The following approach will not have streaming rendering effects. To achieve streaming rendering effects, refer to [Streaming SSR](/guides/basic-features/render/streaming-ssr.md).
+
+:::
+
+```ts title="src/routes/page.data.ts"
+export const loader = () => {
+  return {
+    message: 'Hello World',
+  };
+};
+```
+
+Access data in components through Hooks API:
+
+```tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+export default () => {
+  const data = useLoaderData();
+  return <div>{data.message}</div>;
+};
+```
+
+### Using Client Loader
+
+By default, in SSR applications, the `loader` function only executes on the server. However, in some scenarios, developers might want requests made on the client-side to bypass the SSR service and directly fetch data from the source. For example:
+
+1. Reducing network consumption on the client-side by directly fetching from the data source.
+2. The application has data cached on the client side and doesn't want to fetch data from the SSR service.
+
+Modern.js supports adding a `.data.client` file, also named exported as `loader`, in SSR applications. If the Data Loader fails to execute on the server side, or when navigating on the client side, it will execute the `loader` function on the client side instead of sending a data request to the SSR service.
+
+```ts title="page.data.client.ts"
+import cache from 'my-cache';
+
+export async function loader({ params }) {
+  if (cache.has(params.id)) {
+    return cache.get(params.id);
+  }
+  const res = await fetch(`URL_ADDRESS?id=${params.id}`);
+  const data = await res.json();
+  return {
+    message: data.message,
+  }
+}
+```
+
+## SSR Fallback
+
+In Modern.js, if an application encounters an error during SSR, it automatically falls back to CSR mode and re-fetches data, ensuring the page can display correctly. SSR fallback can occur for two main reasons:
+
+1. Data Loader execution error.
+2. React component rendering error on the server side.
+
+### Data Loader Execution Error
+
+By default, if the `loader` function for a route throws an error, the framework renders the `<ErrorBoundary>` component directly on the server, displaying the error message. This is the default behavior of most frameworks.
+
+Modern.js also supports customizing the fallback strategy through the `loaderFailureMode` field in the [`server.ssr`](/configure/app/server/ssr.md) configuration. Setting this field to `clientRender` immediately falls back to CSR mode and re-fetches the data.
+
+If a Client Loader is defined for the route, it will be used to re-fetch the data. If re-rendering fails again, the `<ErrorBoundary>` component will be displayed.
+
+
+### Component Rendering Error
+
+If the Data Loader executes correctly but the component rendering fails, SSR rendering will partially or completely fail, as shown in the following code:
+
+```tsx
+import { Await, useLoaderData } from '@modern-js/runtime/router';
+import { Suspense } from 'react';
+
+const Page = () => {
+  const data = useLoaderData();
+  const isNode = typeof window === 'undefined';
+  const undefinedVars = data.unDefined;
+  const definedVars = data.defined;
+
+  return (
+    <div>
+      {isNode ? undefinedVars.msg : definedVars.msg}
+    </div>
+  );
+};
+
+export default Page;
+```
+
+In this case, Modern.js will fallback the page to CSR and use the existing data from the Data Loader to render. If the rendering still fails, the `<ErrorBoundary>` component will be rendered.
+
+:::tip
+The behavior of component rendering errors is unaffected by `loaderFailureMode` and will not execute the Client Loader on the browser side.
+:::
+
+
+## Logging and Monitoring
+
+:::tip
+SSR monitoring has been integrated into the Monitors module, see [Monitors](/guides/advanced-features/server-monitor/monitors.md) for details.
+:::
+
+## Page Caching
+
+Modern.js has built-in caching capabilities. Refer to [Rendering Cache](/guides/basic-features/render/ssr-cache.md) for details.
+
+## Differences in Runtime Environment
+
+SSR applications run on both the server and the client, with differing Web and Node APIs.
+
+When enabling SSR, Modern.js uses the same entry to build both SSR and CSR bundles. Therefore, having Web APIs in the SSR bundle or Node APIs in the CSR bundle can lead to runtime errors. This usually happens in two scenarios:
+
+- There are issues in the application's own code.
+- The dependency package contains side effects.
+
+### Issues with Own Code
+
+This scenario often arises when migrating from CSR to SSR. CSR applications typically import Web APIs in the code. For example, an application might set up global event listeners:
+
+```tsx
+document.addEventListener('load', () => {
+  console.log('document load');
+});
+const App = () => {
+  return <div>Hello World</div>;
+};
+export default App;
+```
+
+In such cases, you can use Modern.js built-in environment variables `MODERN_TARGET` to remove unused code during the build:
+
+```ts
+if (process.env.MODERN_TARGET === 'browser') {
+  document.addEventListener('load', () => {
+    console.log('document load');
+  });
+}
+```
+
+After packing in the development environment, the SSR and CSR bundles will compile as follows. Therefore, Web API errors will not occur in the SSR environment:
+
+```ts
+// SSR Bundle
+if (false) {
+}
+
+// CSR Bundle
+if (true) {
+  document.addEventListener('load', () => {
+    console.log('document load');
+  });
+}
+```
+
+:::note
+For more information, see [Environment Variables](/guides/basic-features/env-vars.md).
+:::
+
+### Side Effects in Dependencies
+
+This scenario can occur at any time in SSR applications because not all community packages support running in both environments. Some packages only need to run in one. For instance, importing package A that has a side effect using Web APIs:
+
+```ts title="packageA"
+document.addEventListener('load', () => {
+  console.log('document load');
+});
+
+export const doSomething = () => {}
+```
+
+Directly referencing this in a component will cause SSR to throw errors, even if you use environment variables to conditionally load the code. The side effects in the dependency will still execute.
+
+```tsx title="routes/page.tsx"
+import { doSomething } from 'packageA';
+
+export const Page = () => {
+  if (process.env.MODERN_TARGET === 'browser') {
+    doSomething();
+  }
+  return <div>Hello World</div>
+}
+```
+
+Modern.js supports distinguishing between SSR and CSR bundles by using `.server.` suffix files. You can create `.ts` and `.server.ts` files with the same name to create a proxy:
+
+```ts title="a.ts"
+export { doSomething } from 'packageA';
+```
+
+```ts title="a.server.ts"
+export const doSomething: any = () => {};
+```
+
+Import `./a` in the file, and the SSR bundle will prioritize the `.server.ts` files, while the CSR bundle will prioritize the `.ts` files.
+
+```tsx title="routes/page.tsx"
+import { doSomething } from './a'
+
+export const Page = () => {
+  doSomething();
+  return <div>Hello World</div>
+}
+```
+
+## Common Issues
+
+### Ensuring Consistent Rendering
+
+In SSR applications, it is crucial to ensure that the rendering results on the server are consistent with the hydration results in the browser. Inconsistent rendering may lead to unexpected outcomes. Here’s an example demonstrating issues when SSR and CSR render differently. Add the following code to your component:
+
+```tsx
+{
+  typeof window !== 'undefined' ? <div>browser content</div> : null;
+}
+```
+
+After starting the application and visiting the page, you will notice a warning in the browser console:
+
+```sh
+Warning: Expected server HTML to contain a matching <div> in <div>.
+```
+
+This warning is caused by a mismatch between the React hydrate results and the SSR rendering results. Although the current page appears normal, complex applications may experience DOM hierarchy disruptions or style issues.
+
+:::info
+For more information on React hydrate logic, refer to [here](https://zh-hans.react.dev/reference/react-dom/hydrate).
+:::
+
+The application needs to maintain consistency between SSR and CSR rendering results. If inconsistencies occur, it indicates that some content should not be rendered by SSR. Modern.js provides the `<NoSSR>` utility component for such scenarios:
+
+```ts
+import { NoSSR } from '@modern-js/runtime/ssr';
+```
+
+Wrap elements that should not be server-side rendered with the `NoSSR` component:
+
+```tsx
+<NoSSR>
+  <div>browser content</div>
+</NoSSR>
+```
+
+After modifying the code, refresh the page and notice that the previous warning has disappeared. Open the browser's developer tools and check the Network tab. The returned HTML document will not contain the content wrapped by the `NoSSR` component.
+
+In practical scenarios, some UI displays might be affected by the user's device, such as [UA](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) information. Modern.js also provides APIs like `use(RuntimeContext)`, allowing components to access complete request information and maintaining SSR and CSR rendering consistency. For detailed usage, please refer to [Runtime Context](/guides/basic-features/render/before-render.md#runtime-context).
+
+### Attention to Memory Leaks
+
+:::warning Alert
+In SSR scenarios, developers need to pay special attention to memory leaks. Even minor memory leaks can significantly impact services after many requests.
+:::
+
+With SSR, each browser request triggers server-side component rendering. Therefore, you should avoid defining any data structures that continually grow globally, subscribing to global events, or creating non-disposable streams.
+
+For example, when using [redux-observable](https://redux-observable.js.org/), developers accustomed to CSR might code as follows:
+
+```tsx
+/* Code is just an example and not executable */
+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>;
+}
+```
+
+In this case, the `epicMiddleware` instance is created outside the component, and `epicMiddleware.run` is called within the component.
+
+This code does not cause issues on the client-side. However, in SSR, the Middleware instance remains non-disposable. Each time the component renders, calling `epicMiddleware.run(rootEpic)` adds new event bindings internally, causing the entire object to grow continuously, ultimately affecting application performance.
+
+Such issues are not easily noticed in CSR. When transitioning from CSR to SSR, if you're unsure whether your application has such hidden pitfalls, consider stress testing the application.

package/docs/guides/basic-features/render/streaming-ssr.md

@@ -0,0 +1,264 @@
+# Streaming Server-Side Rendering
+
+Streaming rendering is an advanced rendering method that progressively returns content during the page rendering process, significantly improving user experience.
+
+In traditional SSR rendering, the page is rendered all at once, requiring all data to be loaded before returning the complete HTML. In streaming rendering, the page is rendered progressively, allowing content to be returned as it renders, so users can see initial content faster.
+
+:::info Default Mode
+**Streaming SSR is the default rendering mode for Modern.js SSR**. When you enable SSR, streaming rendering is available without additional configuration.
+
+If you need to switch to traditional SSR mode (waiting for all data to load before returning at once), you can configure `server.ssr.mode` to `'string'`. For detailed information, refer to the [Server-Side Rendering (SSR)](/guides/basic-features/render/ssr.md) documentation.
+:::
+
+Compared to traditional SSR rendering:
+
+- **Faster Perceived Speed**: Streaming rendering can progressively display content, quickly rendering the home page.
+- **Enhanced User Experience**: Users can see page content faster and interact without waiting for the entire page to render.
+- **Better Performance Control**: Developers can better control the loading priority and order, optimizing performance and user experience.
+- **Better Adaptability**: Streaming rendering adapts better to various network speeds and device performance, ensuring good performance across different environments.
+
+## Enabling Streaming Rendering
+
+Modern.js supports React 18+ streaming rendering. When you enable SSR, streaming rendering is enabled by default:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: true, // Streaming rendering enabled by default
+  },
+});
+```
+
+If you need to explicitly specify streaming rendering mode, you can configure:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: {
+      mode: 'stream', // Explicitly specify streaming rendering mode
+    },
+  },
+});
+```
+
+Modern.js streaming rendering is based on React Router and involves several key APIs:
+
+- [`Await`](https://reactrouter.com/en/main/components/await): Used to render the asynchronous data returned by the Data Loader.
+- [`useAsyncValue`](https://reactrouter.com/en/main/hooks/use-async-value): Used to fetch data from the nearest parent `Await` component.
+
+## Fetching Data
+
+```ts title="user/[id]/page.data.ts"
+import { defer, type LoaderFunctionArgs } from '@modern-js/runtime/router';
+
+interface User {
+  name: string;
+  age: number;
+}
+
+export interface Data {
+  data: User;
+}
+
+export const loader = ({ params }: LoaderFunctionArgs) => {
+  const userId = params.id;
+
+  const user = new Promise<User>(resolve => {
+    setTimeout(() => {
+      resolve({
+        name: `user-${userId}`,
+        age: 18,
+      });
+    }, 200);
+  });
+
+  return defer({ data: user });
+};
+```
+
+Here, `user` is a Promise object representing asynchronously fetched data, processed using `defer`. Notice that `defer` must receive an object parameter; a direct Promise cannot be passed.
+
+Additionally, `defer` can receive both asynchronous and synchronous data. In the example below, short-duration requests are returned using object data, while longer-duration requests are returned using a Promise:
+
+```ts title="user/[id]/page.data.ts"
+export const loader = async ({ params }: LoaderFunctionArgs) => {
+  const userId = params.id;
+
+  const user = new Promise<User>(resolve => {
+    setTimeout(() => {
+      resolve({
+        name: `user-${userId}`,
+        age: 18,
+      });
+    }, 2000);
+  });
+
+  const otherData = new Promise<string>(resolve => {
+    setTimeout(() => {
+      resolve('some sync data');
+    }, 200);
+  });
+
+  return defer({
+    data: user,
+    other: await otherData,
+  });
+};
+```
+
+This way, the application can prioritize displaying partially available content without waiting for the most time-consuming data requests.
+
+## Rendering Data
+
+To render the asynchronous data returned by the Data Loader, use the `Await` component. For example:
+
+```tsx title="user/[id]/page.tsx"
+import { Await, useLoaderData } from '@modern-js/runtime/router';
+import { Suspense } from 'react';
+import type { Data } from './page.data';
+
+const Page = () => {
+  const data = useLoaderData() as Data;
+
+  return (
+    <div>
+      User info:
+      <Suspense fallback={<div id="loading">loading user data ...</div>}>
+        <Await resolve={data.data}>
+          {user => {
+            return (
+              <div id="data">
+                name: {user.name}, age: {user.age}
+              </div>
+            );
+          }}
+        </Await>
+      </Suspense>
+    </div>
+  );
+};
+
+export default Page;
+```
+
+The `Await` component needs to be wrapped inside a `Suspense` component. The `resolve` prop of `Await` should be the asynchronously fetched data from the Data Loader. When the data is fetched, it will be rendered using the [Render Props](https://zh-hans.react.dev/reference/react/cloneElement#passing-data-with-a-render-prop) pattern. During data fetching, the content set by the `fallback` prop of `Suspense` is displayed.
+
+:::warning Warning
+When importing types from the `page.data.ts` file, use `import type` to ensure only type information is imported, preventing Data Loader code from being bundled into the frontend.
+:::
+
+In the component, you can also fetch asynchronous data returned by the Data Loader using `useAsyncValue`. For example:
+
+```tsx title='page.tsx'
+import { useAsyncValue } from '@modern-js/runtime/router';
+
+const UserInfo = () => {
+  const user = useAsyncValue();
+  return (
+    <div>
+      name: {user.name}, age: {user.age}
+    </div>
+  );
+};
+
+const Page = () => {
+  const data = useLoaderData() as Data;
+  return (
+    <div>
+      User info:
+      <Suspense fallback={<div id="loading">loading user data ...</div>}>
+        <Await resolve={data.data}>
+          <UserInfo />
+        </Await>
+      </Suspense>
+    </div>
+  );
+};
+
+export default Page;
+```
+
+## Error Handling
+
+The `errorElement` prop of the `Await` component handles errors in Data Loader or sub-component rendering. For example, intentionally throwing an error in the Data Loader function:
+
+```ts title="page.loader.ts"
+import { defer } from '@modern-js/runtime/router';
+
+export default () => {
+  const data = new Promise((resolve, reject) => {
+    setTimeout(() => {
+      reject(new Error('error occurs'));
+    }, 200);
+  });
+
+  return defer({ data });
+};
+```
+
+Then, fetch the error using `useAsyncError` and set a component to render the error message for the `errorElement` prop of the `Await` component:
+
+```tsx title="page.ts"
+import { Await, useAsyncError, useLoaderData } from '@modern-js/runtime/router';
+import { Suspense } from 'react';
+
+export default function Page() {
+  const data = useLoaderData();
+
+  return (
+    <div>
+      Error page
+      <Suspense fallback={<div>loading ...</div>}>
+        <Await resolve={data.data} errorElement={<ErrorElement />}>
+          {(data: any) => {
+            return <div>never displayed</div>;
+          }}
+        </Await>
+      </Suspense>
+    </div>
+  );
+}
+
+function ErrorElement() {
+  const error = useAsyncError() as Error;
+  return <p>Something went wrong! {error.message}</p>;
+}
+```
+
+## Controlling When to Wait for Full HTML
+
+Streaming improves perceived speed, but in some cases (SEO crawlers, A/B buckets, compliance pages) you may want to wait for all content before sending the response.
+
+Modern.js decides the streaming mode with this priority:
+
+1. Request header `x-should-stream-all` (set per-request in middleware).
+2. Env `MODERN_JS_STREAM_TO_STRING` (forces full HTML).
+3. [isbot](https://www.npmjs.com/package/isbot) check on `user-agent` (bots get full HTML).
+4. Default: stream shell first.
+
+Set the header in your middleware to choose the behavior dynamically:
+
+```ts title="middleware example"
+export const middleware = async (ctx, next) => {
+  const ua = ctx.req.header('user-agent') || '';
+  const shouldWaitAll = /Lighthouse|Googlebot/i.test(ua) || ctx.req.path === '/marketing';
+
+  // Write a boolean string: true -> onAllReady, false -> onShellReady
+  ctx.req.headers.set('x-should-stream-all', String(shouldWaitAll));
+
+  await next();
+};
+```
+
+
+## Related Documentation
+
+- [Rendering Mode Overview](/guides/basic-features/render/overview.md)
+- [Server-Side Rendering (SSR)](/guides/basic-features/render/ssr.md)
+- [Rendering Cache](/guides/basic-features/render/ssr-cache.md)
+- [React Server Components (RSC)](/guides/basic-features/render/rsc.md) - Use with Streaming SSR
+- [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37) - React 18 Architecture Overview