Histoire

Vue 3 和 Svelte 的 Vite 原生组件 Story 工具

组件开发文档工具VueVite

由 Nuxt 团队成员参与打造，提供美观 UI、内置可访问性检查和极快开发体验，是 Vue 生态中 Storybook 的主要轻量替代。

Histoire Vue 组件开发与文档工具技术调研

Histoire 是专为 Vue 3 和 Svelte 设计的 Vite 原生组件 Story 工具，由 Nuxt 团队成员参与打造，提供美观的 UI、内置可访问性检查和极快的开发体验。它是 Vue 生态中 Storybook 的主要轻量替代，特别适合 Vite + Vue 组件库的日常调试与文档展示。

一、基本信息

维度	关键指标 / 描述
技术标签	Vue 3 / Svelte / Vite / 组件 Story / 文档
开发商	Histoire 开源社区
官方网站	https://histoire.dev/
GitHub 仓库	histoire-dev/histoire
npm 包	`histoire`
许可协议	MIT License
首次发布	2022 年
当前版本	Histoire 0.17.x+
生态成熟度	中（Vue 社区快速增长）

二、技术定位与简介

Histoire（法语「故事」）特点：

Vite 原生：与 Vue/Vite 项目无缝集成。
<Story> 组件：在 .story.vue 文件中编写多状态 Story。
响应式预览：内置多视口、暗色模式。
内置 a11y：组件级可访问性检查面板。
Markdown 文档：Story 内嵌文档说明。
静态构建：生成组件文档静态站。

适合 Vue 3 组件库、packages/ui 调试，以及不愿配置繁重 Storybook 的 Vue 团队。

三、快速上手安装说明

1. 安装

pnpm add -D histoire @histoire/plugin-vue

2. histoire.config.ts

import { defineConfig } from 'histoire'
import { HstVue } from '@histoire/plugin-vue'
 
export default defineConfig({
  plugins: [HstVue()],
  setupFile: '/src/histoire.setup.ts',
})

3. Button.story.vue

<script setup lang="ts">
import Button from './Button.vue'
</script>
 
<template>
  <Story title="Components/Button">
    <Variant title="Primary">
      <Button variant="primary">Click</Button>
    </Variant>
    <Variant title="Disabled">
      <Button disabled>Disabled</Button>
    </Variant>
  </Story>
</template>

4. 运行

pnpm histoire dev

5. 构建

pnpm histoire build

四、核心特性

1. .story.vue 单文件 Story

Vue SFC 风格，符合 Vue 开发者习惯。

2. Controls

HstSelect、HstCheckbox 等内置控件绑定 props。

3. 响应式工具栏

切换视口尺寸、主题、背景。

实时 axe 检查。

5. 事件检查

组件 emit 事件可视化。

6. Svelte 支持

@histoire/plugin-svelte。

7. Nuxt 集成

社区模块支持 Nuxt 项目。

五、适用场景

1. 黄金适用场景

Vue 3 + Vite 组件开发与调试。
Vue 设计系统文档站。
组件多状态、响应式布局预览。
组件 a11y 开发期检查。
Storybook 配置过重时的替代。

2. 局限适用场景

React 项目（用 Storybook/Ladle）。
需要 Chromatic 级视觉回归官方集成。
复杂跨框架设计系统。
大型企业插件生态需求。

六、技术亮点

1. Vue 原生体验

.story.vue 与组件写法一致。

2. Vite 速度

冷启动与 HMR 快。

3. 美观默认 UI

开箱即用现代界面。

无需额外 addon 配置。

5. Nuxt 生态亲和

与 Vue 现代工具链同一心智。

七、核心概念与架构

digraph Histoire_Arch {
  rankdir=TB
  node [shape=box, style="rounded,filled", fillcolor="#f0f9ff"]
  Histoire [label="Histoire Core", fillcolor="#bae6fd"]
  Vite [label="Vite"]
  Plugin [label="@histoire/plugin-vue"]
  Stories [label="*.story.vue"]
  UI [label="Histoire UI"]
 
  Histoire -> Vite
  Histoire -> Plugin
  Stories -> Histoire
  Histoire -> UI
}

八、技术局限与边界

框架局限：主要 Vue/Svelte，非全框架。
生态小于 Storybook：插件、教程、企业案例少。
测试 Runner：无官方 Playwright Test Runner 对标。
版本 0.x：API 可能仍有演进。
React 不支持：跨框架团队需双工具。
MDX 生态：弱于 Storybook Docs。

九、生态地图

类别	工具
Vue	@histoire/plugin-vue
Svelte	@histoire/plugin-svelte
对比	Storybook Vue、VitePress
测试	Vitest + @vue/test-utils

十、生态集成

方向	说明
Pinia	setupFile 注册 store。
vue-i18n	setup 中配置 i18n 实例。
Tailwind	histoire.setup 导入样式。
Nuxt	社区 histoire-nuxt 模块。

十一、开发与工程化

1. histoire.setup.ts

import './styles/main.css'
import { createPinia } from 'pinia'
 
export function setupVue3({ app }) {
  app.use(createPinia())
}

2. 与 VitePress 分工

Histoire 组件级；VitePress 项目文档级。

十二、性能与安全

本地/内网文档部署为主。
Story 使用 Mock 数据，避免生产 API。

十三、技术对比

工具	优势	局限	适合
Histoire	Vue 原生、快、a11y	生态小	Vue 组件调试
Storybook	全框架、插件多	Vue 配置重	跨框架设计系统
VitePress	项目文档	非组件 Story	技术文档站

十四、最佳实践

每个公共组件至少一个 .story.vue。
setupFile 统一 Pinia、i18n、全局样式。
Variant 覆盖主要用户可见状态。
开发期关注 a11y 面板告警。
复杂逻辑用 Vitest 测，Story 负责可视化。
与 packages/ui 目录结构对齐。

十五、学习与社区资源

官方文档：https://histoire.dev/guide/
GitHub：https://github.com/histoire-dev/histoire
Vue 生态介绍：Nuxt/Vite 社区博客

Histoire

Histoire Vue 组件开发与文档工具技术调研

一、 基本信息

二、 技术定位与简介

三、 快速上手安装说明