@modern-js/main-doc 3.0.0-alpha.0 → 3.0.0-alpha.1

package/docs/en/guides/advanced-features/international/configuration.mdx

@@ -105,6 +105,7 @@ i18nPlugin({
 1. **If you configure `loadPath` or `addPath`**: The backend will be automatically enabled (`enabled: true`) without checking for locales directory, since you've already specified the resource path.
 
 2. **If you don't configure backend**: The plugin will automatically detect if a `locales` directory exists in:
+
    - Project root: `{projectRoot}/locales`
    - Config public directory: `{projectRoot}/config/public/locales`
    - Public directory configured via `server.publicDir`: `{projectRoot}/{publicDir}/locales`
@@ -331,27 +332,17 @@ export default defineRuntimeConfig({
 
 ### i18nInstance Configuration
 
-If you need to use a custom i18next instance, you can provide it in runtime configuration:
-
-```ts
-import { defineRuntimeConfig } from '@modern-js/runtime';
-import i18next from 'i18next';
+If you need to use a custom i18n instance, you can provide it in runtime configuration:
 
-// Create custom instance
-const customI18n = i18next.createInstance({
-  // Custom configuration
-});
+import CustomInstanceCode from '@site-docs/components/international/custom-instance-code';
 
-export default defineRuntimeConfig({
-  i18n: {
-    i18nInstance: customI18n,
-  },
-});
-```
+<CustomInstanceCode />
 
 ### initOptions Configuration
 
-`initOptions` will be passed to i18next's `init` method and supports all i18next configuration options:
+import InitOptionsDesc from '@site-docs/components/international/init-options-desc';
+
+<InitOptionsDesc />
 
 :::info
 If `localePathRedirect` is enabled, the `detection` configuration should be set in CLI configuration, not in `initOptions`. This is because the server-side plugin needs to read the `detection` option from CLI configuration to perform language detection and path redirection.

package/docs/en/guides/advanced-features/international/quick-start.mdx

@@ -10,14 +10,9 @@ This guide will help you quickly integrate internationalization functionality in
 
 First, install the necessary dependencies:
 
-```bash
-pnpm add @modern-js/plugin-i18n i18next react-i18next
-```
-
-:::info
-`i18next` and `react-i18next` are peer dependencies and need to be installed manually.
+import InstallCommand from '@site-docs/components/international/install-command';
 
-:::
+<InstallCommand />
 
 ## Basic Configuration
 
@@ -56,32 +51,9 @@ export default defineConfig({
 
 ### Configure Runtime Options in `src/modern.runtime.ts`
 
-Create the `src/modern.runtime.ts` file and configure i18n runtime options:
+import InstanceCode from '@site-docs/components/international/instance-code';
 
-```ts
-import { defineRuntimeConfig } from '@modern-js/runtime';
-import i18next from 'i18next';
-
-// It's recommended to create a new i18next instance to avoid using the global default instance
-const i18nInstance = i18next.createInstance();
-
-export default defineRuntimeConfig({
-  i18n: {
-    i18nInstance: i18nInstance,
-    initOptions: {
-      fallbackLng: 'en',
-      supportedLngs: ['zh', 'en'],
-    },
-  },
-});
-```
-
-:::info
-`modern.runtime.ts` is a runtime configuration file used to configure i18next initialization options. Even for the most basic configuration, it's recommended to create this file to ensure the plugin works correctly.
-
-It's recommended to use `i18next.createInstance()` to create a new instance instead of directly using the default exported `i18next`. This avoids global state pollution and ensures each application has an independent i18n instance.
-
-:::
+<InstanceCode />
 
 ### Create Language Resource Files
 

package/docs/en/guides/advanced-features/page-performance/optimize-bundle.mdx

@@ -40,7 +40,7 @@ If you want to find out the large libraries in the project, you can add the `BUN
 BUNDLE_ANALYZE=true pnpm build
 ```
 
-See the [performance.bundleAnalyze](/configure/app/performance/bundle-analyze.html) configuration for details.
+This will generate a bundle analysis report to help you identify large dependencies.
 
 ## Adjust Browserslist
 

package/docs/en/guides/advanced-features/page-performance/react-compiler.mdx

@@ -6,11 +6,25 @@ Before starting to use the React Compiler, it is recommended to read the [React
 
 ## How to Use
 
-The steps to use the React Compiler in Modern.js are as follows:
+### React 19
 
-1. Modern.js does not officially support React 19 yet, but you can install `react-compiler-runtime@rc` in React 17 or 18 projects to allow the compiled code to run on versions before 19.
+If you are using React 19, Modern.js has built-in support for React Compiler, and no additional configuration is required.
 
-2. Currently, the React Compiler only provides a Babel plugin, so you need to install `babel-plugin-react-compiler`.
+### React 17 or 18
+
+If you are using React 17 or 18, you need to configure it as follows:
+
+1. Install `react-compiler-runtime` to allow the compiled code to run on versions before 19:
+
+```bash
+npm install react-compiler-runtime
+```
+
+2. Install `babel-plugin-react-compiler`:
+
+```bash
+npm install babel-plugin-react-compiler
+```
 
 3. Register the Babel plugin in your Modern.js configuration file:
 
@@ -24,7 +38,7 @@ export default defineConfig({
         [
           'babel-plugin-react-compiler',
           {
-            target: '18',
+            target: '18', // or '17', depending on your React version
           },
         ],
       ]);

package/docs/en/guides/advanced-features/rspack-start.mdx

@@ -73,7 +73,7 @@ export default defineConfig({
 ```
 
 :::tip
-When Rspack build is enabled, `babel-loader` is not enabled by default. If you need to add some babel plugins, you can configure it through [tools.babel](/configure/app/tools/babel). This will generate additional compilation overhead and slow down the Rspack build speed to a certain extent.
+When Rspack build is enabled, `babel-loader` is not enabled by default. If you need to add some babel plugins, you can configure it through [babel plugin](https://rsbuild.rs/plugins/list/plugin-babel#babel-plugin). This will generate additional compilation overhead and slow down the Rspack build speed to a certain extent.
 :::
 
 ## The relationship between Rspack and Modern.js versions

package/docs/en/guides/advanced-features/server-monitor/monitors.mdx

@@ -73,11 +73,7 @@ Modern.js comes with a built-in default Monitor, where different events trigger
 
 ## Register Monitors
 
-Developers can register their own Monitors using the `push` API, but this can only be done in [server middleware](/guides/advanced-features/web-server#unstable-middleware) or server plugins. Registration is not available in Data Loaders, components, or init functions.
-
-:::note
-Server plugins are currently not available, and documentation will be added in the future.
-:::
+Developers can register their own Monitors using the `push` API, but this can only be done in [server middleware](/guides/advanced-features/web-server#unstable-middleware) or [server plugins](/plugin/server-plugins/api). Registration is not available in Data Loaders, components, or init functions.
 
 ```ts title="server/modern.server.ts"
 import {
@@ -114,6 +110,67 @@ export default defineServerConfig({
 });
 ```
 
+Register Monitor in server plugins:
+
+```ts title="server/plugins/my-monitor-plugin.ts"
+import type { ServerPlugin } from '@modern-js/server-runtime';
+import type { MonitorEvent } from '@modern-js/types';
+
+const myMonitorPlugin = (): ServerPlugin => ({
+  name: '@my-org/my-monitor-plugin',
+  setup(api) {
+    api.onPrepare(() => {
+      const { middlewares } = api.getServerContext();
+
+      // Define monitor, ensuring it's only created once
+      const myMonitor = (event: MonitorEvent) => {
+        if (event.type === 'log') {
+          // Handle log events
+          console.log(`[${event.payload.level}] ${event.payload.message}`);
+        } else if (event.type === 'timing') {
+          // Handle timing events
+          console.log(
+            `Timing: ${event.payload.name} = ${event.payload.dur}ms`,
+          );
+        } else if (event.type === 'counter') {
+          // Handle counter events
+          console.log(`Counter: ${event.payload.name}`);
+        }
+      };
+
+      // Use a flag to ensure monitor is only registered once
+      let monitorRegistered = false;
+
+      middlewares.push({
+        name: 'inject-monitor',
+        handler: async (c, next) => {
+          const monitors = c.get('monitors');
+          // Only register monitor on the first request
+          if (!monitorRegistered) {
+            monitors.push(myMonitor);
+            monitorRegistered = true;
+          }
+          await next();
+        },
+      });
+    });
+  },
+});
+
+export default myMonitorPlugin;
+```
+
+Then configure the plugin in `server/modern.server.ts`:
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+import myMonitorPlugin from './plugins/my-monitor-plugin';
+
+export default defineServerConfig({
+  plugins: [myMonitorPlugin()],
+});
+```
+
 ## Use Monitors
 
 Modern.js allows developers to invoke Monitors in Data Loaders and components.

package/docs/en/guides/basic-features/data/data-cache.mdx

@@ -2,14 +2,11 @@
 title: Data Caching
 sidebar_position: 4
 ---
+
 # Data Caching
 
 The `cache` function allows you to cache the results of data fetching or computation, Compared to full-page [rendering cache](/guides/basic-features/render/ssr-cache), it provides more fine-grained control over data granularity and is applicable to various scenarios such as Client-Side Rendering (CSR), Server-Side Rendering (SSR), and API services (BFF).
 
-:::info
-X.65.5 and above versions are required
-:::
-
 ## Basic Usage
 
 :::note
@@ -20,7 +17,6 @@ If you use the `cache` function in BFF, you should import the cache funtion from
 
 :::
 
-
 ```ts
 import { cache } from '@modern-js/runtime/cache';
 import { fetchUserData } from './api';
@@ -28,14 +24,13 @@ import { fetchUserData } from './api';
 const getUser = cache(fetchUserData);
 
 const loader = async () => {
-  const user = await getUser(user); // When the parameters of the function changes, the function will be re-executed
+  const user = await getUser('123'); // When the parameters of the function changes, the function will be re-executed
   return {
     user,
   };
 };
 ```
 
-
 ### Parameters
 
 - `fn`: The data fetching or computation function to be cached
@@ -44,7 +39,7 @@ const loader = async () => {
   - `maxAge`: Cache validity period (milliseconds)
   - `revalidate`: Time window for revalidating the cache (milliseconds), similar to HTTP Cache-Control's stale-while-revalidate functionality
   - `getKey`: Simplified cache key generation function based on function parameters
-  - `customKey`: Custom cache key function
+  - `customKey`: Custom cache key generation function, used to maintain cache when function references change
 
 The type of the `options` parameter is as follows:
 
@@ -62,7 +57,6 @@ interface CacheOptions {
 }
 ```
 
-
 ### Return Value
 
 The `cache` function returns a new function with caching capabilities. Multiple calls to this function will not re-execute the `fn` function.
@@ -76,7 +70,7 @@ EdenX's `cache` function can be used in any frontend or server-side code.
 
 ### Without options Parameter
 
-When no `options` parameter is provided, it's primarily useful in SSR projects, the cache lifecycle is limited to a single SSR rendering request. For example, when the same cachedFn is called in multiple data loaders, the cachedFn function won't be executed repeatedly. This allows data sharing between different data loaders while avoiding duplicate requests. EdenX will re-execute the `fn` function with each server request.
+When no `options` parameter is provided, it's primarily useful in SSR projects, the cache lifecycle is limited to a single SSR rendering request. For example, when the same cachedFn is called in multiple data loaders, the cachedFn function won't be executed repeatedly. This allows data sharing between different data loaders while avoiding duplicate requests. Modern.js will re-execute the `fn` function with each server request.
 
 :::info
 Without the `options` parameter, it can be considered a replacement for React's [`cache`](https://react.dev/reference/react/cache) function and can be used in any server-side code (such as in data loaders of SSR projects), not limited to server components.
@@ -96,7 +90,6 @@ const loader = async () => {
 };
 ```
 
-
 ### With options Parameter
 
 #### `maxAge` Parameter
@@ -113,12 +106,11 @@ const getDashboardStats = cache(
     return await fetchComplexStatistics();
   },
   {
-    maxAge: CacheTime.MINUTE * 2,  // Calling this function within 2 minutes will return cached data
-  }
+    maxAge: CacheTime.MINUTE * 2, // Calling this function within 2 minutes will return cached data
+  },
 );
 ```
 
-
 #### `revalidate` Parameter
 
 The `revalidate` parameter sets a time window for revalidating the cache after it expires. It can be used together with the `maxAge` parameter, similar to HTTP Cache-Control's stale-while-revalidate mode.
@@ -139,11 +131,10 @@ const getDashboardStats = cache(
   {
     maxAge: CacheTime.MINUTE * 2,
     revalidate: CacheTime.MINUTE * 1,
-  }
+  },
 );
 ```
 
-
 #### `tag` Parameter
 
 The `tag` parameter identifies the cache with a tag, which can be a string or an array of strings.
@@ -158,7 +149,7 @@ const getDashboardStats = cache(
   },
   {
     tag: 'dashboard',
-  }
+  },
 );
 
 const getComplexStatistics = cache(
@@ -167,13 +158,12 @@ const getComplexStatistics = cache(
   },
   {
     tag: 'dashboard',
-  }
+  },
 );
 
-await revalidateTag('dashboard-stats'); // Invalidates the cache for both getDashboardStats and getComplexStatistics functions
+await revalidateTag('dashboard'); // Invalidates the cache for both getDashboardStats and getComplexStatistics functions
 ```
 
-
 #### `getKey` Parameter
 
 The `getKey` parameter simplifies cache key generation, especially useful when you only need to rely on part of the function parameters to differentiate caches. It's a function that receives the same parameters as the original function and returns a string.
@@ -193,15 +183,15 @@ const getUser = cache(
     maxAge: CacheTime.MINUTE * 5,
     // Only use the first parameter (userId) as the cache key
     getKey: (userId, options) => userId,
-  }
+  },
 );
 
 // The following two calls will share the cache because getKey only uses userId
-await getUser(123, { language: 'en' });
-await getUser(123, { language: 'fr' }); // Cache hit, won't request again
+await getUser(123, { language: 'zh' });
+await getUser(123, { language: 'en' }); // Cache hit, won't request again
 
 // Different userId will use different cache
-await getUser(456, { language: 'en' }); // Won't hit cache, will request again
+await getUser(456, { language: 'zh' }); // Won't hit cache, will request again
 ```
 
 You can also use Modern.js's `generateKey` function together with getKey to generate the cache key:
@@ -223,21 +213,18 @@ const getUser = cache(
   {
     maxAge: CacheTime.MINUTE * 5,
     getKey: (userId, options) => generateKey(userId),
-  }
+  },
 );
 ```
 
 Additionally, `getKey` can also return a numeric type as a cache key:
 
 ```ts
-const getUserById = cache(
-  fetchUserDataById,
-  {
-    maxAge: CacheTime.MINUTE * 5,
-    // Directly use the numeric ID as the cache key
-    getKey: (id) => id,
-  }
-);
+const getUserById = cache(fetchUserDataById, {
+  maxAge: CacheTime.MINUTE * 5,
+  // Directly use the numeric ID as the cache key
+  getKey: id => id,
+});
 
 await getUserById(42); // Uses 42 as the cache key
 ```
@@ -255,6 +242,7 @@ Its return value **directly becomes** the final cache key, **overriding** the de
 :::info
 
 Generally, the cache will be invalidated in the following scenarios:
+
 1. The function's input parameters change
 2. The maxAge condition is no longer satisfied
 3. The `revalidateTag` method has been called
@@ -270,16 +258,13 @@ import { cache } from '@modern-js/runtime/cache';
 import { fetchUserData } from './api';
 
 // Different function references, but share the same cache via customKey
-const getUserA = cache(
-  fetchUserData,
-  {
-    maxAge: CacheTime.MINUTE * 5,
-    customKey: ({ params }) => {
-      // Return a stable string as the cache key
-      return `user-${params[0]}`;
-    },
-  }
-);
+const getUserA = cache(fetchUserData, {
+  maxAge: CacheTime.MINUTE * 5,
+  customKey: ({ params }) => {
+    // Return a stable string as the cache key
+    return `user-${params[0]}`;
+  },
+});
 
 // Even if the function reference changes,
 // as long as customKey returns the same value, the cache will be hit
@@ -291,7 +276,7 @@ const getUserB = cache(
       // Return the same key as getUserA
       return `user-${params[0]}`;
     },
-  }
+  },
 );
 
 // Now you can share cache across different function implementations
@@ -299,12 +284,9 @@ await getUserA(123); // Fetches data and caches with key "user-123"
 await getUserB(123); // Cache hit, returns cached data
 
 // You can utilize the generatedKey parameter to modify the default key
-const getUserC = cache(
-  fetchUserData,
-  {
-    customKey: ({ generatedKey }) => `prefix-${generatedKey}`,
-  }
-);
+const getUserC = cache(fetchUserData, {
+  customKey: ({ generatedKey }) => `prefix-${generatedKey}`,
+});
 
 // For predictable cache keys that can be managed externally
 const getUserD = cache(
@@ -314,7 +296,7 @@ const getUserD = cache(
   {
     maxAge: CacheTime.MINUTE * 5,
     customKey: ({ params }) => `app:user:${params[0]}`,
-  }
+  },
 );
 ```
 
@@ -331,30 +313,31 @@ const stats = {
   hits: 0,
   misses: 0,
   stales: 0,
-  hitRate: () => stats.hits / stats.total
+  hitRate: () => stats.hits / stats.total,
 };
 
-const getUser = cache(
-  fetchUserData,
-  {
-    maxAge: CacheTime.MINUTE * 5,
-    onCache({ status, key, params, result }) {
-      // status can be 'hit', 'miss', or 'stale'
-      stats.total++;
-
-      if (status === 'hit') {
-        stats.hits++;
-      } else if (status === 'miss') {
-        stats.misses++;
-      } else if (status === 'stale') {
-        stats.stales++;
-      }
-
-      console.log(`Cache ${status} for key: ${String(key)}`);
-      console.log(`Current hit rate: ${stats.hitRate() * 100}%`);
+const getUser = cache(fetchUserData, {
+  maxAge: CacheTime.MINUTE * 5,
+  onCache({ status, key, params, result }) {
+    // status can be 'hit', 'miss', or 'stale'
+    stats.total++;
+
+    if (status === 'hit') {
+      stats.hits++;
+    } else if (status === 'miss') {
+      stats.misses++;
+    } else if (status === 'stale') {
+      stats.stales++;
     }
-  }
-);
+
+    console.log(
+      `Cache ${
+        status === 'hit' ? 'hit' : status === 'miss' ? 'miss' : 'stale'
+      } for key: ${String(key)}`,
+    );
+    console.log(`Current hit rate: ${stats.hitRate() * 100}%`);
+  },
+});
 
 // Usage example
 await getUser(1); // Cache miss
@@ -375,6 +358,7 @@ The `onCache` callback receives an object with the following properties:
 This callback is only invoked when the `options` parameter is provided. When using the cache function without options, the `onCache` callback is not called.
 
 The `onCache` callback is useful for:
+
 - Monitoring cache performance
 - Calculating hit rates
 - Logging cache operations
@@ -432,7 +416,7 @@ configureCache({
 
 ##### Using `customKey` to Ensure Cache Key Stability
 
-:::note
+:::warning Important Recommendation
 
 When using custom storage containers (such as Redis), **it's recommended to configure `customKey`** to ensure cache key stability. This ensures:
 
@@ -461,7 +445,7 @@ const getUser = cache(
     maxAge: CacheTime.MINUTE * 5,
     // Use stable identifiers related to the cached function as cache keys
     customKey: () => `fetchUserData`,
-  }
+  },
 );
 ```
 
@@ -481,7 +465,7 @@ class RedisContainer implements Container {
   }
 
   async get(key: string): Promise<string | null> {
-    const value = await this.redis.get(key);
+    const value = await this.client.get(key);
     return value ? JSON.parse(value) : null;
   }
 
@@ -524,7 +508,7 @@ configureCache({
 });
 ```
 
-##### Important Notes
+##### Notes
 
 1. **Serialization**: All cached data will be serialized to strings for storage. The container only needs to handle string get/set operations.
 

package/docs/en/guides/basic-features/data/data-fetch.mdx

@@ -8,10 +8,6 @@ Modern.js provides out-of-the-box data fetching capabilities. Developers can use
 
 ## What is Data Loader
 
-:::note
-In Modern.js v1 projects, data was fetched using `useLoader`. This is no longer the recommended approach; we suggest migrating to Data Loader.
-:::
-
 Modern.js recommends managing routes using [conventional routing](/guides/basic-features/routes/routes). Each route component (`layout.ts`, `page.ts`, or `$.tsx`) can have a same-named `.data` file. These files can export a `loader` function, known as Data Loader, which executes before the corresponding route component renders to provide data for the component. Here is an example:
 
 ```bash
@@ -39,15 +35,18 @@ export const loader = async (): Promise<ProfileData> => {
 ```
 
 :::warning Compatibility
+
 - In previous versions, Data Loader was defined in a `.loader` file. In the current version, we recommend defining it in a `.data` file, while maintaining compatibility with `.loader` files.
 - In `.loader` files, the Data Loader can be exported as default. In `.data` files, it should be named `loader` export.
+
 ```ts
-  // xxx.loader.ts
-export default () => {}
+// xxx.loader.ts
+export default () => {};
 
 // xxx.data.ts
-export const loader = () => {}
+export const loader = () => {};
 ```
+
 :::
 
 In the route component, you can use the `useLoaderData` function to fetch data:
@@ -100,7 +99,7 @@ export const loader = async ({ params }: LoaderFunctionArgs) => {
 `request` is an instance of [Fetch Request](https://developer.mozilla.org/en-US/docs/Web/API/Request). A common use case is to get query parameters from `request`:
 
 ```tsx
-import { LoaderFunctionArgs } from '@modern-js/runtime/router;
+import { LoaderFunctionArgs } from '@modern-js/runtime/router';
 
 export const loader = async ({ request }: LoaderFunctionArgs) => {
   const url = new URL(request.url);
@@ -146,20 +145,22 @@ In SSR applications, the `loader` function runs only on the server, hence it is
 
 :::note
 Having the `loader` function run only on the server in SSR applications brings several benefits:
+
 - **Simplifies usage**: Guarantees consistent data-fetching methods in SSR applications, so developers don't have to distinguish between client and server code.
 - **Reduces client bundle size**: Moves logic code and dependencies from the client to the server.
 - **Improves maintainability**: Less direct influence of data logic on front-end UI and avoids issues of accidentally including server dependencies in the client bundle or vice versa.
 
 :::
 
-We recommend using the `fetch` API in `loader` functions to make requests. Since `fetch` works similarly on the client and server, you can fetch data in a consistent manner whether in CSR or SSR:
+We recommend using the `fetch` API in `loader` functions to make requests. Modern.js provides a default polyfill for the `fetch` API, allowing it to be used on the server side. This means you can fetch data in a consistent manner whether in CSR or SSR:
 
 ```tsx
 export async function loader() {
   const res = await fetch('URL_ADDRESS');
+  const data = await res.json();
   return {
-    message: res.message
-  }
+    message: data.message,
+  };
 }
 ```
 
@@ -204,14 +205,14 @@ In the following example, the page's status code will match this `response`, and
 // routes/user/profile/page.data.ts
 export async function loader() {
   const user = await fetchUser();
-  if(!user){
+  if (!user) {
     throw new Response('The user was not found', { status: 404 });
   }
   return user;
 }
 
 // routes/error.tsx
-import { useRouteError } from '@modern-js/runtime/router;
+import { useRouteError } from '@modern-js/runtime/router';
 const ErrorBoundary = () => {
   const error = useRouteError() as { data: string };
   return <div className="error">{error.data}</div>;
@@ -240,7 +241,7 @@ export function UserLayout() {
 }
 ```
 
-`useRouteLoaderData` accepts a parameter `routeId`. In conventional routing, Modern.js automatically generates the `routeId`, which is the path of the corresponding component relative to `src/routes`. In the example above, the `routeId` for fetching data from `routes/user/layout.tsx`'s loader is `user/layout`.
+`useRouteLoaderData` accepts a parameter `routeId`. In conventional routing, Modern.js automatically generates the `routeId`, which is the path of the corresponding component relative to `src/routes`. For example, in the example above, if a child component wants to get data returned by the loader in `routes/user/layout.tsx`, the `routeId` value is `user/layout`.
 
 In a multi-entry scenario, the `routeId` value needs to include the corresponding entry name, which is typically the directory name if not explicitly specified. For example, with the following directory structure: