Modern.js

字节跳动开源的渐进式 React Web 开发框架，基于 Rspack（Rust 构建引擎）驱动，提供从路由、数据获取到微前端的完整现代 Web 工程化方案。

技术简介说明

Modern.js 是由字节跳动 Web Infra 团队开源的渐进式 React Web 开发框架。它以 Rspack（基于 Rust 的高性能打包工具）和 Rsbuild 为核心构建引擎，支持约定式路由、嵌套路由、服务端渲染（SSR）、静态站点生成（SSG）、React Server Components（RSC）、BFF（Backend For Frontend）以及微前端（Module Federation 2.0）等现代 Web 开发能力。Modern.js 在字节跳动内部被广泛使用，驱动了近 70% 的活跃 Web 项目，经过大规模生产环境验证。

与传统 Web 框架不同，Modern.js 采用「渐进式」设计理念——开发者可以按需引入框架能力，从零配置启动到逐步启用高级特性，无需一次性承担全部学习成本。3.0 版本标志着框架的重大战略转型：移除了 webpack 支持全面拥抱 Rspack，将服务端架构迁移到 Hono 中间件体系，并将 Module 和 Doc 工具独立为 Rslib 和 Rspress 项目，使 Modern.js 更聚焦于 Web 应用开发本身。

Modern.js 背后的 web-infra-dev 组织还维护着 Rspack、Rsbuild、Rspress、Rslib 等一系列高性能前端工具链，形成了完整的 Rust 前端工具生态。这些工具之间深度协同，使 Modern.js 在构建速度、包体积和开发体验上均具有显著优势。

基本信息

快速上手

环境准备

# 确保 Node.js >= 20（推荐 22 LTS）
node -v
 
# 安装 pnpm（推荐）
npm install -g pnpm@10

安装

# 方式一：在已有空目录中创建
mkdir myapp && cd myapp
npx @modern-js/create@latest
 
# 方式二：直接指定项目名创建
npx @modern-js/create@latest myapp
 
# 初始化 Git 和安装依赖
cd myapp
git init
pnpm install

基础配置

modern.config.ts 是项目的核心配置文件：

import { appTools, defineConfig } from '@modern-js/app-tools';
 
export default defineConfig({
  // 插件注册（appTools 为必选核心插件）
  plugins: [appTools()],
 
  // 服务端配置
  server: {
    ssr: true,      // 启用 SSR
    // rsc: true,   // 启用 React Server Components
  },
 
  // 构建配置
  output: {
    // 输出目录等
  },
 
  // 开发服务器配置
  dev: {
    port: 8080,
  },
});

最小示例

项目创建后的标准目录结构：

.
├── biome.json                # Biome 配置（Lint + 格式化）
├── modern.config.ts          # Modern.js 配置文件
├── package.json
├── tsconfig.json
└── src
    ├── modern-app-env.d.ts   # 类型声明
    ├── modern.runtime.ts     # 运行时配置
    └── routes
        ├── layout.tsx        # 全局布局组件
        └── page.tsx          # 首页组件（/）

src/routes/page.tsx：

import './index.css';
 
export default function Home() {
  return (
    <div className="container">
      <main>
        <h1>Modern.js App</h1>
        <p>Get started by editing src/routes/page.tsx</p>
      </main>
    </div>
  );
}

src/routes/layout.tsx：

import { Outlet } from 'react-router-dom';
 
export default function Layout() {
  return (
    <div>
      <Outlet />
    </div>
  );
}

常用命令

构建产物结构

dist
├── html/index
├── routes-manifest.json
├── modern.config.json
└── static
    ├── css
    └── js

核心概念与架构

Rspack 构建引擎

Modern.js 3.0 完全基于 Rspack 构建，彻底移除了 webpack 支持。Rspack 是基于 Rust 编写的高性能打包工具，与 webpack 生态高度兼容：

• 极速构建：相比 webpack，编译速度提升数倍
• 持久化缓存：非首次构建提速 50%+（默认开启）
• Barrel 文件优化：组件库构建提速 20%（默认开启）
• 安装体积减少：npm 依赖减少 40%，安装体积减少 31 MB

文件约定式路由

Modern.js 采用文件系统即路由的设计理念，src/routes/ 目录下的文件自动映射为路由：

• routes/page.tsx → /
• routes/layout.tsx → 全局布局包裹
• 支持动态路由、嵌套路由、可选路由段
• 3.0 新增 src/modern.routes.ts 支持配置式路由，与约定式路由共存

// src/modern.routes.ts - 配置式路由
export default defineRoutes(({ route, layout, page }) => {
  return [
    route('home.tsx', '/'),
    route('about.tsx', 'about'),
    route('blog.tsx', 'blog/:id'),
  ];
});

插件系统（三层架构）

Modern.js 3.0 开放了完整的全链路插件体系：

1. CLI 插件：扩展构建阶段功能，添加命令、修改配置
2. 运行时插件：在 CSR / SSR 渲染时执行，核心钩子包括：
   • onBeforeRender：渲染前执行逻辑（数据预取、全局数据注入）
   • wrapRoot：包裹根组件（添加全局 Provider、布局组件）
3. 服务端插件：基于 Hono 中间件体系，支持鉴权、数据预取、降级处理和动态 HTML 注入

Data Loader（数据加载）

Modern.js 内置了基于路由级别的数据加载方案，每个路由可以定义独立的 loader 函数：

• 支持服务端和客户端数据获取
• 与 SSR / SSG 深度集成
• 路由切换时自动合并多个 Data Loader 请求为单一流式请求

React Router v7

3.0 版本内置 React Router v7（v5 和 v6 已废弃）：

• v6 用户可无损升级到 v7
• v5 用户需按照 React Router 官方迁移指南进行迁移
• 完全兼容 React Router 生态

核心特性

1. React Server Components（RSC）

3.0 版本集成了 React Server Components，同时支持 CSR 和 SSR 项目：

// modern.config.ts
export default defineConfig({
  server: {
    rsc: true,
  },
});

• 所有路由组件默认为 Server Component
• 使用 "use client" 指令标记客户端组件
• 路由切换时自动合并 Data Loader 和 Server Component 请求
• 嵌套路由中，子路由组件类型独立于父路由，支持渐进式迁移

2. 多渲染模式

开箱即用支持多种渲染模式，满足不同场景需求：

3. BFF（Backend For Frontend）

支持在同一项目中开发 BFF 代码，前后端一体化：

• 基于 Hono 运行时，通过 useHonoContext 访问完整请求上下文
• 支持跨项目调用 BFF 函数，无需独立部署服务
• 函数调用风格简洁，降低跨端数据获取复杂度

4. Module Federation 2.0 微前端

深度集成 Module Federation 2.0：

• MF SSR：Module Federation 支持 SSR 流式应用
• 应用级模块：支持导出完整应用级模块（含完整路由能力），而非仅组件级
• 生产者通过 createBridgeComponent 导出，消费者通过 createRemoteAppComponent 加载
• 通配符路由（$.tsx）自动处理所有子路径

5. 服务端渲染增强

• 渲染缓存：缓存完整 SSR 结果页面，支持 stale-while-revalidate 策略
• 数据缓存：细粒度 cache() 函数避免多 Loader 重复请求
• 灵活降级策略：
  • 错误降级（Error Fallback）：Data Loader 错误触发 ErrorBoundary
  • 渲染错误降级：SSR 出错时回退到 CSR
  • 业务降级：Loader 抛出 throw Response 携带 HTTP 状态码
  • 客户端 Loader：绕过 SSR 在客户端获取数据
  • 强制降级：通过 ?__csr=true 查询参数或请求头跳过 SSR

6. 多种样式方案

支持主流 CSS 解决方案，可按项目需求灵活选择：

• CSS Modules：零配置开箱即用
• Tailwind CSS：内置支持
• CSS-in-JS：支持 Styled Components 等方案

7. 零配置启动 + 全量可配置

• 零配置即可启动项目，合理默认值覆盖大多数场景
• 所有配置项均可自定义，满足特殊需求
• 配置 API 类型安全，提供完善的 TypeScript 推导

8. 路由调试工具

运行 npx modern routes 生成 dist/routes-inspect.json：

• 结构化报告每个路由的路径、组件、Data Loader、ErrorBoundary、Loading 组件
• JSON 格式对 AI Agent 友好，支持辅助调试

生态图

Modern.js 背后是一个完整的 Rust 前端工具生态：

┌─────────────────────────────────────────────────────────────┐
│                    Modern.js 应用框架                        │
│              （渐进式 React Web 开发框架）                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │   Rspack     │  │   Rsbuild    │  │    Rspress       │  │
│  │  Rust 打包器  │  │  Rspack 构建  │  │  静态站点生成器   │  │
│  │              │  │    工具       │  │   (文档站点)     │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │    Rslib     │  │   Garfish    │  │  Module Fed 2.0  │  │
│  │  库开发工具   │  │   微前端框架  │  │    微前端模块     │  │
│  │              │  │              │  │     联邦         │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │  Storybook   │  │    Biome     │  │   Rsbuild        │  │
│  │  Rsbuild 版   │  │  Lint/格式化  │  │   Storybook      │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

核心生态项目

插件生态

适用场景

1. 企业级中后台应用

• 内置路由、数据获取、状态管理方案，适合复杂中后台
• 零配置启动 + 渐进式引入高级特性
• 字节跳动内部大量中后台项目验证

2. 内容驱动型网站（SSR / SSG）

• 开箱即用的 SSR / SSG 多渲染模式
• RSC 支持零客户端包体积，优化 SEO 和首屏性能
• 灵活的缓存策略和降级方案

3. 微前端架构

• 深度集成 Module Federation 2.0
• 支持 MF SSR 流式微前端
• 应用级模块导出，支持完整路由能力
• 与 Garfish 微前端框架配合使用

4. BFF 一体化项目

• 前后端代码同项目开发，降低接口联调成本
• Hono 运行时，高性能轻量
• 支持跨项目 BFF 函数调用

5. 需要极致构建速度的大型项目

• Rspack Rust 构建引擎，速度远超传统 webpack 方案
• 持久化缓存大幅加速非首次构建
• npm 依赖减少 40%，安装体积减少 31 MB

6. 渐进式迁移项目

• 从零配置启动到按需引入特性
• RSC 支持路由级渐进迁移
• 配置式路由与约定式路由共存，方便从其他框架迁移

7. Monorepo 多应用项目

• 与 Turborepo / pnpm workspace 天然兼容
• Rslib / Rspress 独立工具满足库和文档需求
• 统一技术栈和构建配置

开发与工程化

开发流程

# 1. 创建项目
npx @modern-js/create@latest myapp
 
# 2. 启动开发服务器
cd myapp && pnpm install && pnpm run dev
 
# 3. 在 src/routes/ 下新增路由文件即自动生效
# 4. 配置 modern.config.ts 启用 SSR / RSC 等高级特性
# 5. 调试路由：npx modern routes

构建部署

# 构建生产产物
pnpm run build
 
# 本地预览
pnpm run serve
 
# 部署到 Node.js 服务器
# dist/ 目录为完整部署产物

部署目标支持：

• Node.js 服务器（原生支持）
• Vercel / Netlify 等云平台
• Docker 容器化部署
• CDN + SSR 混合部署

最佳实践

1. 零配置起步：不要一开始就大量配置，先使用默认值，按需调整
2. 渐进式引入：先 CSR，再按需启用 SSR / SSG / RSC
3. 使用 Biome：3.0 默认使用 Biome 替代 ESLint + Prettier，更快更统一
4. 利用持久化缓存：默认开启，确保 CI/CD 中缓存目录被正确保存
5. 路由级 RSC 迁移：不必一次迁移整个组件树，按路由逐步迁移
6. Data Loader 优先：统一使用 Data Loader 获取数据，保持数据流清晰
7. 类型安全：充分利用 TypeScript 配置推导，减少运行时错误

性能与安全

性能特点

安装性能

• npm 依赖减少 40%（3.0 对比 2.x）
• 安装体积减少 31 MB
• 更快的 pnpm install 体验

安全考量

• 服务端代码不暴露给客户端（RSC / SSR 逻辑隔离）
• BFF 层可做统一鉴权和权限控制
• Hono 中间件支持安全的请求处理和 CSP 策略
• 生产环境建议启用 HTTPS、安全 Headers 和 CSRF 防护

技术对比

选型建议

• 选 Modern.js：需要极致构建速度、RSC 支持（含 CSR 场景）、微前端、字节内部验证的企业级方案、国内团队优先
• 选 Next.js：需要最广泛的社区支持、Vercel 部署、国际化项目
• 选 Umi：React 技术栈但需要更轻量配置、蚂蚁生态项目
• 选 Nuxt：Vue 技术栈项目

最佳实践

生产环境配置

import { appTools, defineConfig } from '@modern-js/app-tools';
 
export default defineConfig({
  plugins: [appTools()],
 
  server: {
    ssr: true,
    rsc: true,
    // 渲染缓存
    cache: {
      staleWhileRevalidate: true,
    },
  },
 
  // 性能优化
  performance: {
    // 启用持久化缓存
    buildCache: true,
  },
 
  // 安全 Headers
  server: {
    headers: {
      'X-Frame-Options': 'SAMEORIGIN',
      'X-Content-Type-Options': 'nosniff',
    },
  },
});

运行时插件配置

// src/modern.runtime.ts
import { defineRuntimeConfig } from '@modern-js/runtime';
 
export default defineRuntimeConfig({
  plugins: [
    // 运行时插件列表
  ],
});

服务端插件配置

// server/modern.server.ts
import { defineServerConfig } from '@modern-js/app-tools/server';
 
export default defineServerConfig({
  middlewares: [
    // Hono 中间件（鉴权、日志、计时等）
  ],
  renderMiddlewares: [
    // HTML 渲染中间件
  ],
});

CI/CD 最佳实践

1. 缓存 node_modules 和 Rspack 缓存目录，加速 CI 构建
2. 使用 pnpm run build 在 CI 中执行类型检查和构建
3. 利用 npx modern routes 生成路由报告用于自动化测试
4. Docker 部署时多阶段构建，减小镜像体积

技术局限与边界

已知限制

1. 仅支持 React：Modern.js 3.0 是纯 React 框架，不支持 Vue、Svelte 等其他框架（如需其他框架，考虑 Rsbuild 独立使用）
2. 不支持 webpack：3.0 彻底移除 webpack，已有 webpack 插件/Loader 需要确认 Rspack 兼容性
3. React 版本要求：最低 React 18，新项目默认 React 19；React 16/17 用户必须先升级
4. Node.js 版本要求：最低 Node.js 20，不再支持 Node.js 18（已 EOL）
5. React Router v5 已废弃：使用 v5 的项目需要按照官方指南迁移到 v7
6. 社区规模：相比 Next.js，全球社区规模较小，英文资料和第三方集成相对有限
7. 生态边界收窄：Module 和 Doc 工具已独立为 Rslib 和 Rspress，Modern.js 本身只聚焦 Web 应用

不适用场景

• Vue / Svelte / Angular 项目：应使用 Nuxt、SvelteKit 等对应框架
• 纯静态博客：Rspress、Astro 等更轻量
• 纯库/组件开发：Rslib 更专业
• 极致包体积敏感场景：虽然有 RSC 优化，但框架运行时本身有一定开销
• 非 React 的微前端：考虑 Garfish 独立使用或 qiankun

学习资源

官方资源

社区资源

相关教程

• Modern.js 官方文档的「指南（Guide）」部分提供了从零到一的完整教程
• modern-js-examples 仓库包含各种场景的示例项目
• Rspack / Rsbuild 文档有助于理解底层构建机制

2026 年现状

最新版本

• Modern.js v3.x：持续迭代中（截至 2026 年 7 月，npm 最新发布为 v2.71.1 系列的兼容更新，3.x 大版本线持续演进）
• Rspack 2.0：2026 年 4 月正式发布，带来更现代的默认配置和 API 设计
• Rsbuild 2.0：与 Rspack 2.0 同步升级

发展趋势

1. Rust 工具链深化：Rspack 2.0 进一步优化构建性能和 API 设计，Modern.js 持续受益于底层引擎升级
2. RSC 生态成熟：React Server Components 在 Modern.js 中的支持更加完善，CSR + RSC 的差异化优势持续扩大
3. Hono 服务端生态：基于 Hono 的 BFF 和服务端插件体系日趋成熟，与边缘计算（Edge Runtime）的结合是未来方向
4. 微前端深化：Module Federation 2.0 的 SSR 支持和应用级模块导出能力持续增强
5. 工具链独立化：Rspress（文档）、Rslib（库开发）独立后各自快速发展，Modern.js 更聚焦 Web 应用
6. 字节内部驱动：内部近 70% 活跃项目的实战验证持续推动框架迭代
7. Wasm 浏览器支持：Rspack 1.4+ 支持在浏览器中运行（包括 StackBlitz 等在线平台），为在线开发场景提供可能

社区活跃度

• GitHub Stars：~5,000+
• 总提交数：6,829+
• 总发布数：272+
• Discord 和飞书群保持活跃
• 字节跳动内部大规模使用保证持续投入
• web-infra-dev 组织下多个项目（Rspack、Rsbuild、Rspress、Rslib）协同活跃

参考来源：

• Modern.js 官网
• Modern.js GitHub
• Modern.js v3 Release Blog
• Rspack 2.0 发布公告
• Rspack 1.4 发布公告
• 2025/2026 年 JavaScript 明星项目