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

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

@@ -1,23 +1,60 @@
 # Using CSS-in-JS
 
-CSS-in-JS is a technique that allows you to write CSS styles in JS files.
+CSS-in-JS is a technique that allows you to write CSS styles within JS files.
 
-Modern.js integrates the popular CSS-in-JS implementation library [styled-components](https://styled-components.com/), which uses the new JavaScript feature [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) to write component CSS styles. You can directly import the API of [styled-components](https://styled-components.com/) from `@modern-js/runtime/styled` for use.
+Modern.js supports the commonly used community CSS-in-JS library [styled-components](https://styled-components.com/), which uses JavaScript's new feature [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) to write component CSS styles.
 
-When you need to write a `div` component with an internal font color of red, you can implement it as follows:
+The Modern.js plugin `@modern-js/plugin-styled-components` provides support for styled-components and adds server-side rendering capability for styled-components. You can use styled-components by installing the `@modern-js/plugin-styled-components` plugin.
+
+## Using styled-components in Modern.js
+
+First, you need to install the `styled-components` plugin dependency and the `styled-components` library:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm install @modern-js/plugin-styled-components styled-components -D',
+    yarn: 'yarn add @modern-js/plugin-styled-components styled-components -D',
+    pnpm: 'pnpm install @modern-js/plugin-styled-components styled-components -D',
+  }}
+/>
+
+Then configure the `styled-components` plugin in `modern.config.ts`:
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+import { styledComponentsPlugin } from '@modern-js/plugin-styled-components';
+
+export default defineConfig({
+  plugins: [
+    styledComponentsPlugin({
+      // ...
+      displayName: true,
+      minify: process.env.NODE_ENV === 'production',
+    }),
+  ],
+});
+```
+
+The configuration options of the styledComponentsPlugin plugin are the same as those of the [@rsbuild/plugin-styled-components](https://www.npmjs.com/package/@rsbuild/plugin-styled-components) plugin. You can refer to the documentation of [@rsbuild/plugin-styled-components](https://www.npmjs.com/package/@rsbuild/plugin-styled-components) for configuration.
+
+## Writing styles with styled-components
+
+When you need to write a `div` component with red text inside, you can implement it as follows:
 
 ```js
-import styled from '@modern-js/runtime/styled';
+import styled from '@modern-js/plugin-styled-components/styled';
 
 const RedDiv = styled.div`
   color: red;
 `;
 ```
 
-If you need to dynamically set component styles based on the component's `props`, for example, the `primary` property of `props` is `true`, the button color is white, otherwise it is red, you can implement the code as follows:
+When you need to dynamically set component styles based on the component's `props`, for example, when the `primary` attribute of `props` is `true`, the button's color is white, otherwise red, the implementation is as follows:
 
 ```js
-import styled from '@modern-js/runtime/styled';
+import styled from '@modern-js/plugin-styled-components/styled';
 
 const Button = styled.button`
   color: ${props => (props.primary ? 'white' : 'red')};
@@ -25,10 +62,8 @@ const Button = styled.button`
 `;
 ```
 
-For more usage of styled-components, please refer to [styled-components official website](https://styled-components.com/).
-
-Modern.js integrates Babel's [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) plugin internally, and you can configure the plugin through [tools.styledComponents](/configure/app/tools/styled-components).
+For more usage of styled-components, please refer to the [styled-components official website](https://styled-components.com/).
 
-:::tip
-If you need to use other CSS-in-JS libraries such as [styled-jsx](https://www.npmjs.com/package/styled-jsx) and [Emotion](https://emotion.sh/), you need to install the corresponding dependencies first. For specific usage, please refer to the library's official website.
+:::tip Tip
+If you want to use other CSS-in-JS libraries such as [styled-jsx](https://www.npmjs.com/package/styled-jsx), [Emotion](https://emotion.sh/), etc., you need to install the corresponding dependencies first. Please refer to the official websites of the respective libraries for specific usage.
 :::

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

@@ -77,20 +77,6 @@ export default {
 };
 ```
 
-## Custom Class Names
-
-Customizing the class names generated by CSS Modules is also a commonly used function, you can use [output.cssModuleLocalIdentName](/configure/app/output/css-modules.html#cssmodulesexportlocalsconvention) to configure it.
-
-```ts
-export default {
-  output: {
-    cssModuleLocalIdentName: '[hash:base64:4]',
-  },
-};
-```
-
-If you need to customize other configs of CSS Modules, you can set them via [tools.cssLoader](/configure/app/tools/css-loader).
-
 ## Add Type Declaration
 
 When you import CSS Modules in TypeScript code, TypeScript may prompt that the module is missing a type definition:
@@ -181,9 +167,11 @@ For example, there are two files `src/index.ts` and `src/index.module.scss` unde
 import styles from './index.module.scss';
 
 export default () => {
-  <div>
-    <div className={styles.pageHeader}>Page Header</div>
-  </div>;
+  return (
+    <div>
+      <div className={styles.pageHeader}>Page Header</div>
+    </div>
+  );
 };
 ```
 

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

@@ -18,14 +18,14 @@ You can also use Stylus in Modern.js by installing the Stylus plugin provided by
 
 Modern.js has built-in [PostCSS](https://postcss.org/) to transform CSS code.
 
-Please refer to [Rsbuild - Using PostCSS](https://rsbuild.rs/guide/basic/css-usage#using-postcss) for detailed usage.
+Please refer to [Rsbuild - Using PostCSS](https://rsbuild.rs/guide/styling/css-usage) for detailed usage.
 
 ## Using Lightning CSS
 
 Modern.js supports using [Lightning CSS](https://lightningcss.dev/) to convert CSS code. This feature can be turned on by configuring [tools.lightningcssLoader](/configure/app/tools/lightningcss-loader).
 
-Please refer to [Rsbuild - Using Lightning CSS](https://rsbuild.rs/guide/basic/css-usage#lightning-css) for detailed usage.
+Please refer to [Rsbuild - Using Lightning CSS](https://rsbuild.rs/guide/styling/css-usage#lightning-css) for detailed usage.
 
 ## Using Uno CSS
 
-Please read the [Rsbuild - Using UnoCSS](https://rsbuild.rs/zh/guide/basic/unocss) for detailed usage.
+Please read the [Rsbuild - Using UnoCSS](https://rsbuild.rs/guide/styling/unocss) for detailed usage.

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

@@ -2,86 +2,12 @@
 
 [Tailwind CSS](https://tailwindcss.com/) is a CSS framework and design system based on Utility Class, which can quickly add common styles to components, and support flexible extension of theme styles.
 
-To use [Tailwind CSS](https://tailwindcss.com/) in Modern.js, you can follow the steps below:
+## Using Tailwind CSS in Modern.js
 
-1. Run `pnpm run new` in the root directory of your project and make the following selections:
+To use [Tailwind CSS](https://tailwindcss.com/) in Modern.js, you only need to configure it according to the Rsbuild steps. Rsbuild supports Tailwind CSS versions v3 and v4:
 
-```text
-? Please select the operation you want: Enable features
-? Please select the feature name: Enable Tailwind CSS
-```
-
-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`:
-
-```ts title="modern.config.ts"
-import { tailwindcssPlugin } from '@modern-js/plugin-tailwindcss';
-
-export default defineConfig({
-  plugins: [..., tailwindcssPlugin()],
-});
-```
-
-3. Create a `index.css` file and add the following code:
-
-```css title="index.css"
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-```
-
-:::info
-Depending on your needs, you can selectively import the CSS styles provided by Tailwind CSS. Please refer to the [`@tailwind` documentation](https://tailwindcss.com/docs/functions-and-directives#tailwind) for detailed usage of the `@tailwind` directive.
-:::
-
-4. Import the `index.css` file, for example, add the following code in the root component `src/App.jsx`:
-
-```js
-import './index.css';
-```
-
-5. Now you can use the Utility Classes provided by Tailwind CSS in your components:
-
-```tsx
-const Hello = () => (
-  <div className="h-12 w-48">
-    <p className="text-xl font-medium text-black">hello world</p>
-  </div>
-);
-```
-
-## Configuring Tailwind CSS
-
-In Modern.js, you have two ways to configure Tailwind CSS:
-
-1. Using the `tailwind.config.{ts,js}` file, which follows the official usage of Tailwind CSS. Please refer to ["Tailwind CSS - Configuration"](https://tailwindcss.com/docs/configuration) for more details.
-
-```ts title="tailwind.config.ts"
-import type { Config } from 'tailwindcss';
-
-export default {
-  content: ['./src/**/*.{js,jsx,ts,tsx}'],
-} as Config;
-```
-
-:::tip
-Please upgrade Modern.js to version >= MAJOR_VERSION.33.0 to support automatic reading of `tailwind.config.{ts,js}` files.
-:::
-
-2. Using the [tools.tailwindcss](/configure/app/tools/tailwindcss.html) configuration option. This is the old way of configuring Tailwind CSS, and we recommend using the `tailwind.config.{ts,js}` file for configuration.
-
-```ts title="modern.config.ts"
-export default {
-  tools: {
-    tailwindcss: {
-      content: ['./src/**/*.{js,jsx,ts,tsx}'],
-    },
-  },
-};
-```
-
-If you are using both the `tailwind.config.{ts,js}` file and `tools.tailwindcss` option, the configuration defined in `tools.tailwindcss` will take precedence and override the content defined in `tailwind.config.{ts,js}`.
+- [Tailwind CSS v3](https://rsbuild.rs/guide/styling/tailwindcss-v3#tailwind-css-v3)
+- [Tailwind CSS v4](https://rsbuild.rs/guide/styling/tailwindcss)
 
 ## Tailwind CSS Autocomplete
 
@@ -92,20 +18,10 @@ You can follow the steps below to enable the autocomplete feature:
 1. Install the [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) extension in VS Code.
 2. If the root directory of your project does not have a `tailwind.config.{ts,js}` file, you need to create one and write the Tailwind CSS configuration for your current project. Otherwise, the IDE plugin will not work correctly.
 
-## Tailwind CSS Version
-
-Modern.js supports both Tailwind CSS v2 and v3 versions, and the framework will recognize the version of the `tailwindcss` dependency in the project `package.json` file and enable the corresponding configuration. By default, we will install Tailwind CSS v3 version for you.
-
-If your project is still using Tailwind CSS v2, we recommend that you upgrade to v3 to support JIT and other capabilities. For the differences between Tailwind CSS v2 and v3 versions, please refer to the following articles:
-
-- [Tailwind CSS v3.0](https://tailwindcss.com/blog/tailwindcss-v3)
-- [Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide)
-
 ## Browser Compatibility
 
-Tailwind CSS v2 and v3 do not support the IE 11 browser, please refer to:
+Tailwind CSS v3 does not support the IE 11 browser, please refer to:
 
 - [Tailwind CSS v3 - Browser Support](https://tailwindcss.com/docs/browser-support).
-- [Tailwind CSS v2 - Browser Support](https://v2.tailwindcss.com/docs/browser-support)
 
 If you use Tailwind CSS on IE 11 browser, some styles may not be available, please use it with caution.

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,17 +106,20 @@ 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.
 
-In the following example, within the 2-minute period before the cache expires, calls to `getDashboardStats` will return cached data. If the cache has expired (between 2 and 3 minutes), requests will first return the old data, then refresh the data in the background and update the cache.
+In the following example, the cache behavior is divided into three phases based on time:
+
+1. **0 to 2 minutes (within `maxAge`)**: Cache is fresh, returns cached data directly without re-fetching
+2. **2 to 3 minutes (between `maxAge` and `maxAge + revalidate`)**: Cache has expired but is within the revalidation window, returns stale data immediately while re-fetching and updating the cache in the background
+3. **Beyond 3 minutes (exceeding `maxAge + revalidate`)**: Cache is completely expired, re-executes the function to fetch new data
 
 ```ts
 import { cache, CacheTime } from '@modern-js/runtime/cache';
@@ -135,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.
@@ -154,7 +149,7 @@ const getDashboardStats = cache(
   },
   {
     tag: 'dashboard',
-  }
+  },
 );
 
 const getComplexStatistics = cache(
@@ -163,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.
@@ -189,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:
@@ -219,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
 ```
@@ -251,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
@@ -266,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
@@ -287,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
@@ -295,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(
@@ -310,7 +296,7 @@ const getUserD = cache(
   {
     maxAge: CacheTime.MINUTE * 5,
     customKey: ({ params }) => `app:user:${params[0]}`,
-  }
+  },
 );
 ```
 
@@ -327,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
@@ -371,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
@@ -428,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:
 
@@ -457,7 +445,7 @@ const getUser = cache(
     maxAge: CacheTime.MINUTE * 5,
     // Use stable identifiers related to the cached function as cache keys
     customKey: () => `fetchUserData`,
-  }
+  },
 );
 ```
 
@@ -477,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;
   }
 
@@ -520,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.