@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

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

@@ -0,0 +1,92 @@
+# Tailwind 插件变更
+
+Modern.js 3.0 推荐通过 Rsbuild 原生方式接入 Tailwind CSS，不再依赖 `@modern-js/plugin-tailwindcss` 插件，从而充分利用 Rsbuild 提供的更灵活的配置能力和更优的构建体验。
+
+## 迁移步骤
+
+本小节中的迁移操作仅当项目中使用了 `@modern-js/plugin-tailwindcss` 插件，且 `tailwindcss` 版本为 v2 或 v3 时才需要执行。
+
+### 1. 移除旧插件
+
+移除 `@modern-js/plugin-tailwindcss` 依赖和配置。
+
+**2.0 版本：**
+
+```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 版本：**
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  plugins: [],
+});
+```
+
+同时移除 `package.json` 中的 `@modern-js/plugin-tailwindcss` 依赖。
+
+### 2. 配置 PostCSS
+
+创建或更新 `postcss.config.cjs` 文件。
+
+```js title="postcss.config.cjs"
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+  },
+};
+```
+
+### 3. Tailwind CSS 配置迁移
+
+**单一配置情况**：
+
+- 若仅在 `tailwind.config.{ts,js}` 中配置，则无需额外处理
+- 若仅在 `modern.config.ts` 中配置，需将 Tailwind 相关配置移植到 `tailwind.config.{ts,js}` 中
+
+**双重配置情况**：
+
+若在 `tailwind.config.{ts,js}` 与 `modern.config.ts` 中都有配置，需要合并两者的配置内容，并将合并后的配置移植到 `tailwind.config.{ts,js}`。
+
+**特殊目录处理**：
+
+若项目中存在 storybook 或 config/html 目录，需在 `tailwind.config.{ts,js}` 的 `content` 中补充：
+
+```ts title="tailwind.config.ts"
+export default {
+  content: [
+    './src/**/*.{js,jsx,ts,tsx}',
+    './storybook/**/*', // 如果存在 storybook 目录
+    './config/html/**/*.{html,ejs,hbs}', // 如果存在 config/html 目录
+  ],
+};
+```
+
+### 4. CSS 样式引入
+
+将 CSS 导入方式变更为 `@tailwind` 指令方式。
+
+**2.0 版本：**
+
+```css
+@import 'tailwindcss/base.css';
+@import 'tailwindcss/components.css';
+@import 'tailwindcss/utilities.css';
+```
+
+**3.0 版本：**
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+

package/docs/zh/guides/upgrade/web-server.md

@@ -0,0 +1,111 @@
+# 自定义 Web Server 变化
+
+本章节覆盖两类旧版自定义 Server API 的升级
+
+- **unstableMiddleware**
+- **Hook**
+
+这两种写法在旧版中互斥，迁移时请根据项目实际使用的能力选择对应路径。
+
+
+## unstableMiddleware
+
+### 核心差异
+
+- **文件结构**：`server/index.ts` → `server/modern.server.ts`
+- **导出方式**：`unstableMiddleware` 数组 → `defineServerConfig`
+- **Context API**：Modern.js Server Context → Hono Context（`c.req`/`c.res`）
+- **中间件执行**：旧版可不调用 `next()`，新版必须调用后续链路才会执行
+- **响应方式**：`c.response.raw()` → `c.text()` / `c.json()`
+
+### 文件与导出
+
+```typescript
+// 旧版 - server/index.ts
+export const unstableMiddleware: UnstableMiddleware[] = [middleware1, middleware2];
+
+// 新版 - server/modern.server.ts
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  middlewares: [
+    { name: 'middleware1', handler: middleware1 },
+    { name: 'middleware2', handler: middleware2 },
+  ],
+});
+```
+
+### 类型与 next 调用
+
+```typescript
+// 旧版
+import type { UnstableMiddleware, UnstableMiddlewareContext } from '@modern-js/server-runtime';
+const middleware: UnstableMiddleware = async (c: UnstableMiddlewareContext, next) => {
+  return c.response.raw('response'); // 不调用 next 也会继续渲染
+};
+
+// 新版
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+const middleware: MiddlewareHandler = async (c, next) => {
+  await next(); // 必须调用
+  return c.text('response');
+};
+```
+
+### Context API 对照
+
+| 旧版 API               | 新版 API                 | 说明            |
+| -------------------- | ---------------------- | ------------- |
+| `c.request.cookie`   | `getCookie(c, 'key')`  | Cookie 读取      |
+| `c.req.cookie()`     | `getCookie(c, 'key')`  | Hono v4 已废弃    |
+| `c.request.pathname` | `c.req.path`           | 请求路径          |
+| `c.request.host`     | `c.req.header('Host')` | 请求主机          |
+| `c.request.query`    | `c.req.query()`        | 查询参数          |
+| `c.request.headers`  | `c.req.header()`       | 请求头           |
+| `c.response.status`  | `c.status()`           | 响应状态码         |
+| `c.response.set`     | `c.res.headers.set`    | 设置响应头         |
+| `c.response.raw`     | `c.text` / `c.json`    | 响应体           |
+
+
+## afterRender Hook
+
+`afterRender` Hook 用于在页面渲染完成后对 HTML 进行处理。在新版中，需要使用 `renderMiddlewares` 来实现相同的功能。
+
+### 核心差异
+
+- **文件结构**：`server/index.ts` → `server/modern.server.ts`
+- **导出方式**：`hook` 对象中的 `afterRender` → `defineServerConfig` 中的 `renderMiddlewares`
+- **处理方式**：直接修改 HTML 字符串 → 通过中间件获取和修改响应
+
+### 迁移示例
+
+```typescript
+// 旧版 - server/index.ts
+export const afterRender = (ctx, next) => {
+  ctx.template = ctx.template
+    .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>');
+  next();
+};
+
+// 新版 - server/modern.server.ts
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+
+const renderMiddleware: MiddlewareHandler = async (c, next) => {
+  await next(); // 先等待页面渲染
+  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/zh/index.md

@@ -0,0 +1,4 @@
+---
+pageType: home
+---
+# Modern.js - 基于 React 的渐进式 Web 开发框架

package/docs/zh/plugin/_meta.json

@@ -0,0 +1,25 @@
+[
+  "introduction",
+  "plugin-system",
+  {
+    "type": "dir",
+    "name": "cli-plugins",
+    "label": "cli-plugins"
+  },
+  {
+    "type": "dir",
+    "name": "runtime-plugins",
+    "label": "runtime-plugins"
+  },
+  {
+    "type": "dir",
+    "name": "server-plugins",
+    "label": "server-plugins"
+  },
+  {
+    "type": "dir",
+    "name": "official",
+    "label": "official-plugins",
+    "collapsed": true
+  }
+]

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

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