原文 6 Tools for Documenting Your React Components Like a Pro
如果没有人能够理解并找到如何使用我们的组件,那它们有什么用呢?
React 鼓励我们使用组件构建模块化程序。模块化给我们带来了非常多的好处,包括提高了可重用性。然而,如果你是为了贡献和复用组件,最好得让你的组件容易被找到、理解和使用。你需要将其文档化。
目前,使用工具可以帮助我们实现自动化文档工作流程,并使我们的组件文档变得丰富、可视化和可交互。有些工具甚至将这些文档组合为共享组件的工作流程的组成部分。
为了轻而易举地将我们的组件文档化,我收集了一些业界流行的工具,如果你有推荐的组件也可以评论留言。
1. Bit
共享组件的平台
Bit 不仅是一个将组件文档化的工具,它还是一个开源工具,支持你使用所有文件和依赖项封装组件,并在不同应用程序中开箱即用地运行它们。
在 Bit,你可以跨应用地共享和协作组件,你所有共享组件都可以被发现,以便你的团队在项目中查找和使用,并轻松共享他们自己的组件。
在 Bit 中,你共享的组件可以在你们团队中的组件共享中心找到,你可以根据上下文、bundle 体积、依赖项搜索组件,你可以非常快地找到已经渲染好的组件快照,并且选择使用它们。
浏览 bit.dev 上的组件
当你进入组件详情页时,Bit 提供了一个可交互的页面实时渲染展示组件,如果该组件包含 js 或 md 代码,我们可以对其进行代码修改和相关调试。
找到想要使用的组件后,只需使用 NPM 或 Yarn 进行安装即可。你甚至可以使用 Bit 直接开发和安装组件,这样你的团队就可以协作并一起构建。
通过 Bit 共享组件,就不需要再使用存储库或工具,也不需要重构或更改代码,共享、文档化、可视化组件都集中在一起,并且也能实现开箱即用。
快速上手:
Share reusable code components as a team · Bit
teambit/bit
2. StoryBook & Styleguidist
StoryBook 和 StyleGuidist 是非常棒的项目,可以帮助我们开发独立的组件,同时可以直观地呈现和文档化它们。
StoryBook 提供了一套 UI 组件的开发环境。它允许你浏览组件库,查看每个组件的不同状态,以及交互式开发和测试组件。在构建库时,StoryBook 提供了一种可视化和记录组件的简洁方法,不同的 AddOns 让你可以更轻松地集成到不同的工具和工作流中。你甚至可以在单元测试中重复使用示例来确认细微差别的功能。
StyleGuidist 是一个独立的 React 组件开发环境并且具备实时编译指引。它提供了一个热重载的服务器和即时编译指引,列出了组件 propTypes 并展示基于.md 文件的可编辑使用示例。它支持 ES6,Flow 和 TypeScript,并且可以直接使用 Create React App。自动生成的使用文档可以帮助 Styleguidist 作为团队不同组件的文档门户。
类似的工具还有 UiZoo
3. Codesandbox, Stackblitz & friends
组件在线编译器是一种非常巧妙的展示组件和理解他们如何运行的工具。当你可以将它们组合为文档的一部分(或作为共享组件的一部分)时,在线编译器可帮助你快速了解代码的工作方式并决定是否要使用该组件。
Codesandbox 是一个在线编辑器,用于快速创建和展示组件等小项目。创建一些有趣的东西后,你可以通过共享网址向他人展示它。CodeSandbox 具有实时预览功能,可以在你输入代码时显示运行结果,并且可以集成到你的不同工具和开发工作流程中去。
Stackblitz 是一个由 Visual Studio Code 提供支持的“Web 应用程序在线 IDE”。与 Codesnadbox 非常相似,StackBlitz 是一个在线 IDE,你可以在其中创建通过 URL 共享的 Angular 和 React 项目。与 Codesandbox 一样,它会在你编辑时自动安装依赖项,编译,捆绑和热重载。
其他类似工具:
11 React UI Component Playgrounds for 2019
4. Docz
Docz 使你可以更轻松地为你的代码构建 Gtabsy 支持的文档网站。它基于 MDX(Markdown + JSX),即利用 markdown 进行组件文档化。基本上,你可以在项目的任何位置编写.mdx 文件,Docz 会将其转换并部署到 Netlify,简化你自己设计的文档门户的过程。非常有用不是吗?
pedronauck / docz
5. MDX-docs
MDX-docs 允许你使用 MDX 和 Next.js 记录和开发 React 组件。您可以将 markdown 与内联 JSX 混合以展示 React 组件。像往常一样写下 markdown 并使用 ES 导入语法在文档中使用自定义组件。内置组件会将 JSX 代码块渲染为具有可编辑代码并提供实时预览功能,由 react-live 提供支持。
jxnblk / MDX- 文档
6. React Docgen
React DocGen 是一个用于从 React 组件文件中提取信息的 CLI 和工具箱,以便生成文档。它使用 ast-types
和@babel/parser
将源解析为 AST
,并提供处理此AST
的方法。输出 / 返回值是 JSON blob/JavaScript
对象。它通过 React.createClass
,ES2015
类定义或功能(无状态组件)为 React 组件提供了一个默认的定义。功能十分强大。
reactjs/react-docgen
callstack/component-docs