Ladle 轻量 React 组件开发环境技术调研

Ladle 是由 Uber 开源的轻量级 React Story 开发工具，定位为 Storybook 的极简替代方案。基于 Vite 构建，启动和热更新极快，配置几乎为零，适合中小型 React 项目或需要快速组件隔离调试、又不想承担 Storybook 复杂度的团队。

一、 基本信息

二、 技术定位与简介

Ladle 核心理念：Convention over Configuration

• 扫描 *.stories.tsx 文件自动发现 Stories。
• 内置 Vite，与项目 Vite 配置自动合并。
• 无复杂 addons 体系，专注组件展示与 Controls。
• 启动速度通常明显快于 Storybook。

适合 React + Vite 项目的组件调试沙箱，不适合需要庞大插件生态的设计系统企业平台。

三、 快速上手安装说明

1. 安装

pnpm add -D @ladle/react

2. package.json

{
  "scripts": {
    "ladle": "ladle serve",
    "ladle:build": "ladle build"
  }
}

3. Button.stories.tsx

import type { Story } from '@ladle/react'
import { Button } from './Button'
 
export const Primary: Story = () => <Button variant="primary">Click</Button>
export const Secondary: Story = () => <Button variant="secondary">Click</Button>
 
Primary.args = { disabled: false }
Primary.argTypes = { disabled: { control: { type: 'boolean' } } }

4. 运行

pnpm ladle
# 默认 http://localhost:61000

5. 构建静态站点

pnpm ladle:build

四、 核心特性

1. 零配置启动

自动发现 stories，自动读取 vite.config。

2. 极速 HMR

Vite 原生热更新。

3. TypeScript 优先

一等 TS 支持。

4. Controls

基础 argTypes 控件支持。

5. 暗色模式

内置主题切换。

6. 静态导出

ladle build 生成可部署静态站。

7. 小依赖体积

比 Storybook 依赖树小得多。

五、 适用场景

1. 黄金适用场景

• React + Vite 项目快速组件调试。
• 小团队不愿维护 Storybook 配置。
• 内部组件库轻量文档站。
• 原型阶段组件状态探索。

2. 局限适用场景

• Vue/Angular（用 Histoire/Storybook）。
• 需要 a11y、Interactions、Chromatic 等完整生态。
• 大型企业设计系统治理。
• 复杂 MDX 文档需求。

六、 技术亮点

1. 启动速度

开发体验流畅，等待时间短。

2. Vite 配置复用

alias、PostCSS、Tailwind 自动继承。

3. 极简 API

学习成本低于 Storybook CSF3。

4. Uber 生产验证

内部大规模使用后开源。

七、 核心概念与架构

digraph Ladle_Arch {
  rankdir=LR
  node [shape=box, style="rounded,filled", fillcolor="#f0f9ff"]
  Ladle [label="Ladle CLI", fillcolor="#bae6fd"]
  Vite [label="Vite"]
  Stories [label="*.stories.tsx"]
  UI [label="Ladle UI Shell"]
  Comp [label="React Component"]
 
  Ladle -> Vite
  Stories -> Ladle
  Ladle -> UI
  UI -> Comp
}

八、 技术局限与边界

1. 仅 React：不支持 Vue 等框架。
2. 插件生态弱：无 Storybook 级别 addons。
3. 测试集成：无官方 Test Runner，需自行 Vitest。
4. 文档能力：无 Autodocs/MDX 深度集成。
5. 社区规模：问题解答资源少于 Storybook。
6. 企业功能：无 Chromatic 类官方云测。

九、 生态地图

十、 生态集成

十一、 开发与工程化

1. vite.config 合并

Ladle 自动 merge 项目 Vite 配置，注意 server.port 冲突。

2. 全局样式

在 .ladle/components.tsx 导入全局 CSS：

import '../src/styles/globals.css'

3. 与 Storybook 选型

小项目 Ladle；设计系统 Storybook。

十二、 性能与安全

• 本地开发工具，勿暴露含内部 API 的 stories 到公网。
• 静态 build 可部署内网组件文档。

十三、 技术对比

十四、 最佳实践

1. stories 与组件同目录或相邻，便于发现。
2. 复用应用 globals.css 保证样式一致。
3. 复杂 Provider 在 .ladle/components.tsx 统一包裹。
4. 需要 a11y/视觉回归时评估迁移 Storybook。
5. 组件逻辑仍用 Vitest + Testing Library 测试。

十五、 学习与社区资源

• 官方文档：https://www.ladle.dev/docs/
• GitHub：https://github.com/tajo/ladle