加入直播:周四,美国东部时间上午 11 点,Storybook 9 版本发布 & 问答
文档
Storybook 文档

贡献 Storybook 框架

Storybook 框架是一个 Node 包,它能够为元框架(Next.js、NuxtJS、SvelteKit)或构建器(Webpack、Vite)与渲染器(React、Angular、Vue 3、Web 组件等)的组合提供开箱即用的支持。

对于元框架,Storybook 框架还需要处理一些额外的配置,以使 Storybook 的行为与元框架生成的应用程序相似。例如,@storybook/nextjs 在 Storybook 内部重新创建或模拟了 Next.js 应用程序的许多功能

供您参考,您可以查看所有官方 Storybook 框架,包括它们的完整源代码和文档。

如何创建框架

1. 确定包名

包名应以 storybook-framework- 开头,然后与您的框架支持的功能相对应。例如,针对 SvelteKit 的框架可以是 storybook-framework-svelte-kit,而针对使用 Vite 的 Stencil 的框架可以是 storybook-framework-stencil-vite。当不针对元框架时,命名约定是 storybook-framework-<renderer>-<builder>

2. 考虑您的框架需要做什么

目标是让 Storybook 在开箱即用的情况下,尽可能地与您所针对的元框架或构建器-渲染器组合的行为相似。

对于元框架,这意味着尝试重新创建元框架提供的任何构建器或 Babel 配置。您应该尽量在尊重用户现有项目配置的方式下进行。

您的框架支持的库可能存在不同的主版本。请考虑您的框架将支持每个库的哪些版本。您需要考虑这些不同版本中的变化,或者将您的框架拆分为不同的版本/包来支持每个库版本。为了加快维护速度,请考虑为您框架支持的不同库版本添加集成测试。

3. 编写文档

在编写任何代码之前,先编写一份有用的 README 文档,其中包含安装说明和可用功能列表。使用 @storybook/nextjs 的 README 作为模板。先编写文档有助于指导您的其他工作。

4. 编写框架本身

框架可以包含以下部分

package.json (示例)

由于框架是一个 Node 包,它必须包含一个 package.json 文件。这里有一个可以供您开始使用的模板

package.json 模板
package.json
{
  "name": "<your-framework-name>",
  "version": "1.0.0",
  "description": "Storybook for <meta-framework-name> or <renderer> & <builder>",
  "keywords": [
    "Storybook",
    "<meta-framework-name>",
    "<renderer>",
    "<builder>",
    "<anything>",
    "<else>",
    "<relevant>"
  ],
  "homepage": "<your package's homepage>",
  "bugs": {
    "url": "https://github.com/<your-org>/<your-repo>/issues"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/<your-org>/<your-repo>.git",
    "directory": "<path/to/your/framework>"
  },
  "license": "MIT",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "require": "./dist/index.js",
      "import": "./dist/index.mjs"
    },
    "./preset": {
      "types": "./dist/preset.d.ts",
      "require": "./dist/preset.js",
      "import": "./dist/preset.mjs"
    },
    "./preview.js": {
      "types": "./dist/preview.d.ts",
      "require": "./dist/preview.js",
      "import": "./dist/preview.mjs"
    },
    "./package.json": "./package.json"
  },
  "main": "dist/index.js",
  "module": "dist/index.mjs",
  "types": "dist/index.d.ts",
  "files": ["dist/**/*", "types/**/*", "README.md", "*.js", "*.d.ts"],
  "scripts": {
    "check": "tsc --noEmit",
    "test": "..."
  },
  "dependencies": {
    "storybook": "^9.0.0",
    "@storybook/<builder>": "^9.0.0",
    "@storybook/<renderer>": "^9.0.0"
  },
  "devDependencies": {
    "typescript": "x.x.x",
    "<meta-framework>": "^x.x.x",
    "<builder>": "^x.x.x"
  },
  "peerDependencies": {
    "<meta-framework>": "^x.x.x || ^x.x.x",
    "<renderer>": "^x.x.x || ^x.x.x",
    "<builder>": "^x.x.x"
  },
  "engines": {
    "node": ">=20.0.0"
  },
  "publishConfig": {
    "access": "public"
  }
}

关于这些属性的一些注意事项

  • exports: 根路径、./presetpackage.json 导出是必需的。如果您的框架有 preview.js,那么它也是必需的。
  • types: 我们强烈建议您使用 TypeScript 编写框架并分发类型定义。
  • dependenciesdevDependencies: 这些只是示例。您的可能看起来完全不同。
  • peerDependencies: 如果您的框架支持您所针对库的多个版本,请确保在这里体现出来。

preset.js (示例)

预设 API 是您配置 Storybook 核心(您的框架使用哪个构建器和渲染器)、构建器(通过 webpackFinalviteFinal 导出)、Babel(通过 babel 导出)、任何必需的插件以及您的框架可用选项的地方。

preview.js (示例)

(可选的)预览 API 是您配置 Story 渲染的地方,例如全局装饰器或初始化您的框架按预期运行所需的某些运行时配置。如果您的框架需要此文件,请注意您还需要在 preset.js配置 previewAnnotations

types.ts (示例)

如果您使用 TypeScript 编写框架(推荐),您应该导出 StorybookConfig 类型,该类型反映了您的框架可用选项。

5. 测试您的框架

在全新的项目中使用与您的框架尽可能相似的 Storybook 设置进行测试。例如,对于使用 React 和 Webpack5 的 @storybook/nextjs,请从使用 @storybook/react@storybook/builder-webpack5 的项目开始。按照您的 README 中的安装说明进行操作,并确保一切都按预期工作。记住测试您所支持库的不同版本、配置和选项。

6. 告知我们!

一旦它经过充分测试并发布,请在 Discord 的 #showcase 频道中发布公告,或者通过发推文并提及 @storybookjs 来告知我们您的框架。我们希望优秀的社区框架最终能够进入 Storybook 代码库,并被视为“官方”支持。

了解更多关于贡献 Storybook 的信息

  • RFC 流程:用于编写功能请求
  • 代码:用于特性和错误修复
  • 用于开始创建新框架的框架
  • 文档:用于文档改进、更正错别字和澄清
  • 示例:用于新的代码片段