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

package/docs/en/guides/upgrade/tailwindcss.mdx

@@ -0,0 +1,130 @@
+# Tailwind Plugin Changes
+
+Modern.js 3.0 recommends integrating Tailwind CSS through Rsbuild's native approach, no longer relying on the `@modern-js/plugin-tailwindcss` plugin, to fully utilize Rsbuild's more flexible configuration capabilities and better build experience.
+
+## Migration Steps
+
+The migration operations in this section only need to be performed when the project actually uses the `@modern-js/plugin-tailwindcss` plugin.
+
+### 1. Remove Old Plugin
+
+Remove the `@modern-js/plugin-tailwindcss` dependency and configuration.
+
+**2.0 Version:**
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import tailwindcssPlugin from '@modern-js/plugin-tailwindcss';
+
+export default defineConfig({
+  plugins: [tailwindcssPlugin()],
+});
+```
+
+**3.0 Version:**
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  plugins: [],
+});
+```
+
+Also remove the `@modern-js/plugin-tailwindcss` dependency from `package.json`.
+
+### 2. Configure PostCSS
+
+Create or update the `postcss.config.cjs` file.
+
+```js title="postcss.config.cjs"
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+  },
+};
+```
+
+### 3. Tailwind CSS Configuration Migration
+
+**Single Configuration Case**:
+
+- If only configured in `tailwind.config.{ts,js}`, no additional processing is needed
+- If only configured in `modern.config.ts`, you need to migrate Tailwind-related configurations to `tailwind.config.{ts,js}`
+
+**Dual Configuration Case**:
+
+If both `tailwind.config.{ts,js}` and `modern.config.ts` have configurations, you need to merge the configurations from both and migrate the merged configuration to `tailwind.config.{ts,js}`.
+
+**Special Directory Handling**:
+
+If the project has storybook or config/html directories, you need to add them to the `content` in `tailwind.config.{ts,js}`:
+
+```ts title="tailwind.config.ts"
+export default {
+  content: [
+    './src/**/*.{js,jsx,ts,tsx}',
+    './storybook/**/*', // If storybook directory exists
+    './config/html/**/*.{html,ejs,hbs}', // If config/html directory exists
+  ],
+};
+```
+
+### 4. CSS Style Import
+
+Change the CSS import method to the `@tailwind` directive approach.
+
+**2.0 Version:**
+
+```css
+@import 'tailwindcss/base.css';
+@import 'tailwindcss/components.css';
+@import 'tailwindcss/utilities.css';
+```
+
+**3.0 Version:**
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+### 5. Twin.macro Integration
+
+If the project uses twin.macro, you need to configure it manually. If not used, you can skip this step.
+
+**Migration Steps**:
+
+1. Manually install dependencies: `pnpm add twin.macro styled-components babel-plugin-macros -D`
+2. Configure the `babel-plugin-macros` plugin in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  plugins: [appTools()],
+  tools: {
+    babel: {
+      plugins: [
+        [
+          'babel-plugin-macros',
+          {
+            twin: {
+              preset: 'styled-components',
+              config: './tailwind.config.ts',
+            },
+          },
+        ],
+      ],
+    },
+  },
+});
+```
+
+## Tailwind CSS V2 Version Migration
+
+If your project still uses Tailwind CSS v2, we recommend upgrading to v3 to support features like JIT. For differences between Tailwind CSS v2 and v3, please refer to:
+
+- [Tailwind CSS v3.0](https://tailwindcss.com/blog/tailwindcss-v3)
+- [Upgrade Guide](https://v3.tailwindcss.com/docs/upgrade-guide)
+
+Tailwind CSS v2 migration also follows the steps above, but note that the original plugin automatically adapted to differences between Tailwind v2 (`purge` configuration) and v3 (`content` configuration). After removing the plugin, if using v2, you need to use the `purge` configuration item in `tailwind.config.{ts,js}` to specify CSS class names to keep.

package/docs/en/guides/upgrade/web-server.mdx

@@ -0,0 +1,91 @@
+# Custom Web Server Changes
+
+This chapter covers upgrades for two types of legacy custom Server APIs:
+
+- **unstableMiddleware**
+- **Hook**
+
+These two approaches are mutually exclusive in the legacy version. When migrating, please choose the corresponding path based on the capabilities actually used in the project.
+
+## unstableMiddleware
+
+### Core Differences
+
+- **File Structure**: `server/index.ts` → `server/modern.server.ts`
+- **Export Method**: `unstableMiddleware` array → `defineServerConfig`
+- **Context API**: Modern.js Server Context → Hono Context (`c.req`/`c.res`)
+- **Middleware Execution**: Legacy version could skip calling `next()`, new version must call it for subsequent chain execution
+- **Response Method**: `c.response.raw()` → `c.text()` / `c.json()`
+
+### File and Export
+
+```typescript
+// Legacy - server/index.ts
+export const unstableMiddleware: UnstableMiddleware[] = [middleware1, middleware2];
+
+// New - server/modern.server.ts
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  middlewares: [
+    { name: 'middleware1', handler: middleware1 },
+    { name: 'middleware2', handler: middleware2 },
+  ],
+});
+```
+
+### Type and next Call
+
+```typescript
+// Legacy
+import type { UnstableMiddleware, UnstableMiddlewareContext } from '@modern-js/server-runtime';
+const middleware: UnstableMiddleware = async (c: UnstableMiddlewareContext, next) => {
+  return c.response.raw('response'); // Will continue rendering even without calling next
+};
+
+// New
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+const middleware: MiddlewareHandler = async (c, next) => {
+  await next(); // Must call
+  return c.text('response');
+};
+```
+
+### Context API Comparison
+
+| Legacy API               | New API                 | Description            |
+| -------------------- | ---------------------- | ------------- |
+| `c.request.cookie`   | `getCookie(c, 'key')`  | Cookie reading      |
+| `c.req.cookie()`     | `getCookie(c, 'key')`  | Hono v4 deprecated    |
+| `c.request.pathname` | `c.req.path`           | Request path          |
+| `c.request.host`     | `c.req.header('Host')` | Request host          |
+| `c.request.query`    | `c.req.query()`        | Query parameters          |
+| `c.request.headers`  | `c.req.header()`       | Request headers           |
+| `c.response.status`  | `c.status()`           | Response status code         |
+| `c.response.set`     | `c.res.headers.set`    | Set response headers         |
+| `c.response.raw`     | `c.text` / `c.json`    | Response body           |
+
+## afterRender Hook
+
+`afterRender` is only used for HTML processing after page rendering is complete.
+
+```typescript
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+
+const renderMiddleware: MiddlewareHandler = async (c, next) => {
+  await next(); // Wait for page rendering first
+  const { res } = c;
+  const html = await res.text();
+
+  const modified = html
+    .replace('<head>', '<head><meta name="author" content="ByteDance">')
+    .replace('<body>', '<body><div id="loading">Loading...</div>')
+    .replace('</body>', '<script>console.log("Page loaded")</script></body>');
+
+  c.res = c.body(modified, { status: res.status, headers: res.headers });
+};
+
+export default defineServerConfig({
+  renderMiddlewares: [{ name: 'custom-content-injection', handler: renderMiddleware }],
+});
+```

package/docs/en/plugin/_meta.json

@@ -11,6 +11,11 @@
     "name": "runtime-plugins",
     "label": "runtime-plugins"
   },
+  {
+    "type": "dir",
+    "name": "server-plugins",
+    "label": "server-plugins"
+  },
   {
     "type": "dir",
     "name": "official",

package/docs/en/plugin/cli-plugins/_meta.json

@@ -1 +1 @@
-["api", "life-cycle", "migration"]
+["api", "life-cycle"]

package/docs/en/plugin/cli-plugins/api.mdx

@@ -1,6 +1,6 @@
 # CLI Plugin API
 
-This document details the API for Modern.js CLI plugins. CLI plugins allow you to extend and customize the functionality of Modern.js projects during the build and development process.
+Modern.js's CLI plugins allow you to extend and customize the functionality of Modern.js projects during the build and development process.
 
 :::info
 
@@ -28,7 +28,8 @@ const myCliPlugin = (): CliPlugin<AppTools> => ({
 export default myCliPlugin;
 ```
 
-The `setup` function receives an `api` object, which provides all available CLI plugin APIs.
+- `name`: A unique identifier for the plugin.
+- The `setup` function receives an `api` object, which provides all available CLI plugin APIs.
 
 ## Information Retrieval
 
@@ -190,12 +191,12 @@ api.config(() => {
 
 #### `api.modifyBundlerChain`
 
-Modify Webpack or Rspack configuration using the chain API.
+Modify Rspack configuration using the chain API.
 
-- **Type:** `api.modifyBundlerChain(modifyFn: (chain: WebpackChain | RspackChain, utils: WebpackUtils | RspackUtils) => void | Promise<void>)`
+- **Type:** `api.modifyBundlerChain(modifyFn: (chain: RspackChain, utils: RspackUtils) => void | Promise<void>)`
 - **Parameters:**
-  - `modifyFn`: A modification function that receives a `webpack-chain` or `RspackChain` instance and utility functions as parameters.
-- **Execution Phase:** When generating the final Webpack or Rspack configuration.
+  - `modifyFn`: A modification function that receives a `RspackChain` instance and utility functions as parameters.
+- **Execution Phase:** When generating the final Rspack configuration.
 - **Corresponding Rsbuild Hook:** [modifyBundlerChain](https://rsbuild.rs/en/plugins/dev/hooks#modifybundlerchain)
 - **Example:**
 
@@ -250,66 +251,16 @@ api.modifyRspackConfig((config, utils) => {
 
 ---
 
-#### `api.modifyWebpackChain`
-
-Modify the Webpack configuration using [webpack-chain](https://github.com/neutrinojs/webpack-chain) (when using Webpack as the bundler).
-
-- **Type:** `api.modifyWebpackChain(modifyFn: (chain: WebpackChain, utils: WebpackUtils) => void | Promise<void>)`
-- **Parameters:**
-  - `modifyFn`: A modification function that receives a `webpack-chain` instance and utility functions as parameters.
-- **Execution Phase:** When generating the final Webpack configuration.
-- **Example:**
+**Build Configuration Modification Order**
 
-```typescript
-api.modifyWebpackChain((chain, utils) => {
-  // Add a custom Webpack loader
-  chain.module
-    .rule('my-loader')
-    .test(/\.my-ext$/)
-    .use('my-loader')
-    .loader(require.resolve('./my-loader'));
-});
 ```
-
----
-
-#### `api.modifyWebpackConfig`
-
-Directly modify the Webpack configuration object (when using Webpack as the bundler).
-
-- **Type:** `api.modifyWebpackConfig(modifyFn: (config: WebpackConfig, utils: WebpackUtils) => WebpackConfig | Promise<WebpackConfig> | void)`
-- **Parameters:**
-  - `modifyFn`: A modification function that receives the Webpack configuration object and utility functions as parameters. It can return the modified configuration object, a Promise, or nothing (modifying the original object directly).
-- **Execution Phase:** When generating the final Webpack configuration.
-- **Example:**
-
-```typescript
-api.modifyWebpackConfig((config, utils) => {
-  // Disable source map
-  config.devtool = false;
-});
+modifyRsbuildConfig
+modifyBundlerChain
+tools.bundlerChain
+modifyRspackConfig
+tools.rspack
 ```
 
-**Build Configuration Modification Order**
-
-- **Building with Rspack:**
-  ```
-  modifyRsbuildConfig
-  modifyBundlerChain
-  tools.bundlerChain
-  modifyRspackConfig
-  tools.rspack
-  ```
-- **Building with Webpack:**
-  ```
-  modifyBundlerChain
-  tools.bundlerChain
-  modifyWebpackChain
-  tools.webpackChain
-  modifyWebpackConfig
-  tools.webpack
-  ```
-
 ---
 
 #### `api.modifyServerRoutes`
@@ -625,4 +576,3 @@ api.onBeforePrintInstructions(({ instructions }) => {
 ## Other Notes
 
 - Refer to [CLI Plugin Lifecycle](./life-cycle.mdx) to understand the execution order of plugin hooks.
-- Refer to [CLI Plugin Migration Guide](./migration.mdx) to learn how to migrate from the old version of plugins to the new version.

package/docs/en/plugin/cli-plugins/life-cycle.mdx

@@ -36,8 +36,6 @@ flowchart TD
     modifyBundlerChain(modifyBundlerChain)
     modifyRsbuildConfig(modifyRsbuildConfig)
     modifyRspackConfig(modifyRspackConfig)
-    modifyWebpackChain(modifyWebpackChain)
-    modifyWebpackConfig(modifyWebpackConfig)
 
     onBeforeBuild_rsbuild(onBeforeBuild)
     onAfterBuild_rsbuild(onAfterBuild)
@@ -63,8 +61,6 @@ flowchart TD
     registry_rsbuild_hooks --> modifyBundlerChain
     modifyBundlerChain --> modifyRsbuildConfig
     modifyRsbuildConfig --> modifyRspackConfig
-    modifyRspackConfig --> modifyWebpackChain
-    modifyWebpackChain --> modifyWebpackConfig
     registry_rsbuild_hooks --> onBeforeBuild_rsbuild
     onBeforeBuild_rsbuild --> onAfterBuild_rsbuild
     onAfterBuild_rsbuild --> onDevCompileDone

package/docs/en/plugin/introduction.mdx

@@ -18,9 +18,9 @@ Without a plugin system, these requirements might require modifying the framewor
 
 Modern.js offers two main types of plugins: Modern.js framework plugins and Rsbuild build plugins. The choice of which plugin to use depends on your specific needs:
 
-- **Rsbuild Build Plugins:** If your needs are closely related to the build process, especially involving modifications to Webpack or Rspack configuration, then you should choose an Rsbuild plugin. For example:
+- **Rsbuild Build Plugins:** If your needs are closely related to the build process, especially involving modifications to Rspack configuration, then you should choose an Rsbuild plugin. For example:
 
-  - Modifying Webpack/Rspack `loader` or `plugin` configurations.
+  - Modifying Rspack `loader` or `plugin` configurations.
   - Handling new file types.
   - Modifying or compiling file contents.
   - Optimizing or processing build artifacts.
@@ -31,7 +31,7 @@ Modern.js offers two main types of plugins: Modern.js framework plugins and Rsbu
   - Customizing the application's rendering process (e.g., SSR).
   - Adding server-side middleware or handler functions.
 
-In short, use Rsbuild plugins when you need to modify Webpack/Rspack configurations; use Modern.js plugins for other framework-related extensions.
+In short, use Rsbuild plugins when you need to modify Rspack configurations; use Modern.js plugins for other framework-related extensions.
 
 ## Modern.js Framework Plugins
 
@@ -101,12 +101,6 @@ export default defineServerConfig({
 });
 ```
 
-:::tip
-Modern.js officially uses the new plugin mechanism starting from `MAJOR_VERSION.66.0`.
-
-If your current version is lower than MAJOR_VERSION.66.0, you can upgrade by running `npx modern upgrade`.
-:::
-
 ### Developing Plugins
 
 If you need to develop Modern.js framework plugins, please read [Modern.js Plugin System](/plugin/plugin-system) for more information.
@@ -122,12 +116,6 @@ Rsbuild is the underlying build tool for Modern.js. By adding Rsbuild plugins, y
 
 You can register Rsbuild plugins in `modern.config.ts` via the `builderPlugins` option. See [builderPlugins](/configure/app/builder-plugins.html) for details.
 
-:::tip
-Starting from `MAJOR_VERSION.46.0`, Modern.js upgraded its underlying build tool to [Rsbuild](https://rsbuild.rs/).
-
-If your current version is lower than MAJOR_VERSION.46.0, you can upgrade by running `npx modern upgrade`.
-:::
-
 :::info
 You can read [Rsbuild Official Website - Plugins](https://rsbuild.rs/plugins/list/index) to learn more about the Rsbuild plugin system.
 :::
@@ -140,9 +128,9 @@ The following are official Rsbuild plugins that are already built into Modern.js
 
 | Plugin                                                                                 | Description                                                                                                                                     | Modern.js Link                                                                                                                        |
 | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| [React Plugin](https://rsbuild.rs/zh/plugins/list/plugin-react)                        | Provides support for React                                                                                                                      | -                                                                                                                                     |
-| [SVGR Plugin](https://rsbuild.rs/zh/plugins/list/plugin-svgr)                          | Supports converting SVG images into React components                                                                                            | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export)     |
-| [Assets Retry Plugin](https://rsbuild.rs/zh/plugins/list/plugin-assets-retry)          | Automatically retries requests when static asset loading fails                                                                                  | [output.assetsRetry](/configure/app/output/assets-retry.html)                                                                         |
+| [React Plugin](https://rsbuild.rs/plugins/list/plugin-react)                        | Provides support for React                                                                                                                      | -                                                                                                                                     |
+| [SVGR Plugin](https://rsbuild.rs/plugins/list/plugin-svgr)                          | Supports converting SVG images into React components                                                                                            | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export)     |
+| [Assets Retry Plugin](https://rsbuild.rs/plugins/list/plugin-assets-retry)          | Automatically retries requests when static asset loading fails                                                                                  | [output.assetsRetry](/configure/app/output/assets-retry.html)                                                                         |
 | [Type Check Plugin](https://github.com/rspack-contrib/rsbuild-plugin-type-check)       | Runs TypeScript type checking in a separate process                                                                                             | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
 | [Source Build Plugin](https://github.com/rspack-contrib/rsbuild-plugin-source-build)   | For monorepo scenarios, supports referencing source code from other subdirectories and completing builds and hot updates                        | [experiments.sourceBuild](/configure/app/experiments/source-build.html)                                                               |
 | [Check Syntax Plugin](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax)   | Analyzes the syntax compatibility of the build artifacts to determine if there are any advanced syntax features that cause compatibility issues | [security.checkSyntax](/configure/app/security/check-syntax.html)                                                                     |
@@ -154,7 +142,7 @@ The following are official Rsbuild plugins that are already built into Modern.js
 The following are official Rsbuild plugins that are not built into Modern.js:
 
 - [Image Compress Plugin](https://github.com/rspack-contrib/rsbuild-plugin-image-compress): Compresses image resources used in the project.
-- [Stylus Plugin](https://rsbuild.rs/zh/plugins/list/plugin-stylus): Uses Stylus as the CSS preprocessor.
+- [Stylus Plugin](https://rsbuild.rs/plugins/list/plugin-stylus): Uses Stylus as the CSS preprocessor.
 - [UMD Plugin](https://github.com/rspack-contrib/rsbuild-plugin-umd): Used to build UMD format artifacts.
 - [YAML Plugin](https://github.com/rspack-contrib/rsbuild-plugin-yaml): Used to reference YAML files and convert them to JavaScript objects.
 - [TOML Plugin](https://github.com/rspack-contrib/rsbuild-plugin-toml): Used to reference TOML files and convert them to JavaScript objects.
@@ -162,4 +150,4 @@ The following are official Rsbuild plugins that are not built into Modern.js:
 import OtherPlugins from '@site-docs-en/components/other-plugins.mdx';
 
 <OtherPlugins />
-````
+```

package/docs/en/plugin/plugin-system.mdx

@@ -59,12 +59,12 @@ const myPlugin: Plugin = {
   usePlugins: [], // List of plugin instances used internally, defaults to an empty array
 
   // Register new Hooks (optional)
-  registryHook: {},
+  registryHooks: {},
 
   // The entry function of the plugin (required)
   setup(api) {
     // The core logic of the plugin, calling plugin APIs through the api object
-    api.modifyWebpackConfig(config => {
+    api.modifyRspackConfig(config => {
       /* ... */
     });
     api.onPrepare(() => {
@@ -221,7 +221,7 @@ const myPlugin = () => ({
 const myPlugin2 = () => ({
   name: 'my-plugin',
   setup: api => {
-    api.modifyRoutes(async routes => {
+    api.modifyRoutes(routes => {
       // Modify routes
       return routes;
     });

package/docs/en/plugin/runtime-plugins/_meta.json

@@ -1 +1 @@
-["api", "life-cycle", "migration"]
+["api", "life-cycle"]

package/docs/en/plugin/runtime-plugins/api.mdx

@@ -37,7 +37,7 @@ export default myRuntimePlugin;
 ```
 
 - `name`: A unique identifier for the plugin.
-- `setup`: The main logic of the plugin, which receives an `api` object as a parameter. This `api` object is used to register hooks.
+- `setup`: A function that receives an `api` object, which provides all available Runtime plugin APIs.
 
 ## API Overview
 

package/docs/en/plugin/server-plugins/_meta.json

@@ -0,0 +1 @@
+["api", "life-cycle"]