基于 Vite 的組件文檔編寫(xiě)神器，又快又省心
現(xiàn)在 Vite 的生態(tài)逐漸完善，今天給大家介紹一款 React 的組件/應(yīng)用文檔編寫(xiě)神器：vite-plugin-react-pages
目前主流搭建文檔站點(diǎn)的方式：
- Gatsby - 以 GraphQL 為核心，功能相當(dāng)完善，插件生態(tài)豐富。但學(xué)習(xí)曲線高(React)
- Docusaurus - Meta 公司出品。功能強(qiáng)大，與 Gatsby 相似(React)
- dumi - 一款 UmiJS 生態(tài)中的組件開(kāi)發(fā)文檔工具(React)
- Nextra - 一個(gè)基于 Next.js 的靜態(tài)站點(diǎn)生成器。(React)
- VuePress - 包含由 Vue 驅(qū)動(dòng)的主題系統(tǒng)和插件 API，另一個(gè)部分是為書(shū)寫(xiě)技術(shù)文檔而優(yōu)化的默認(rèn)主題(Vue)
- VitePress - 對(duì) VuePress 進(jìn)行了不少的改進(jìn)。VitePress 旨在降低當(dāng)前 VuePress 的復(fù)雜性，并從其極簡(jiǎn)主義的根源重新開(kāi)始。(Vue)
除了 VitePress 之外，其他都是用 Webpack 作為開(kāi)發(fā)服務(wù)器。一個(gè)只有幾頁(yè)的簡(jiǎn)單文檔站點(diǎn)啟動(dòng)開(kāi)發(fā)服務(wù)器所花費(fèi)的時(shí)間變得難以忍受。即使是 HMR 更新也可能需要幾秒鐘才能反映在瀏覽器中。Vite 的出現(xiàn)很好地解決了這些問(wèn)題：近乎即時(shí)的服務(wù)器啟動(dòng)、僅編譯所服務(wù)頁(yè)面的按需編譯以及閃電般快速的 HMR。
作為 Vite 的基礎(chǔ)上的文檔方案， VitePress 只支持 Vue。
翻閱 Vite 的官方庫(kù)列表，偶然發(fā)現(xiàn)了一款 star 數(shù)量?jī)H 100 多的文檔解決方案 vite-plugin-react-pages。開(kāi)始用試試水的心態(tài)去去體驗(yàn)一把，結(jié)果發(fā)現(xiàn)相當(dāng)好用。就是知道的人太少了?，F(xiàn)在，我們從使用者的角度去解析它好用的功能。
特性
vite-plugin-react-pages(vite-pages) 是一個(gè)由 vite 提供支持的 React 應(yīng)用程序框架。它非常適合：
- 博客網(wǎng)站
- 組件庫(kù)或產(chǎn)品的文檔站點(diǎn)
- React 組件的 Demo 演示
它提供了許多幫助開(kāi)發(fā)人員快速構(gòu)建 React App 的功能：
- 很棒的開(kāi)發(fā)體驗(yàn)。即使有很多頁(yè)面，也可以極速啟動(dòng)本地開(kāi)發(fā)服務(wù)器。HMR 適用于 React 和 MDX，因此可以在編輯代碼時(shí)獲得即時(shí)的更新反饋。
- 基于文件系統(tǒng)的路由。通過(guò)遵循簡(jiǎn)單的文件系統(tǒng)路由約定，可以輕松創(chuàng)建、定位和開(kāi)發(fā)頁(yè)面。也可以配置 vite-pages 如何查找頁(yè)面文件，以便支持任何文件結(jié)構(gòu)的項(xiàng)目。
- 支持 MDX?？梢允褂?“普通 React” 或 MDX 編寫(xiě)內(nèi)容。“普通 React” 與 Markdown 靈活組合，更具可讀性和易于編輯。
- 強(qiáng)大的主題定制。vite-pages 本身不渲染任何具體的 DOM 節(jié)點(diǎn)。使用默認(rèn)的官方主題庫(kù)，也可以很容易自己創(chuàng)建一個(gè)主題，可以自定義頁(yè)面上的任何內(nèi)容。
- 基于頁(yè)面的自動(dòng)代碼拆分。只根據(jù)訪問(wèn)需要加載當(dāng)前的頁(yè)面數(shù)據(jù)。
- 支持組件與代碼預(yù)覽。在看到組件功能之后，可以通過(guò)代碼查看組件使用方式。
- 支持 typescript 類(lèi)型提取。將 typescript 的類(lèi)型定義和注釋生成為組件 API 文檔表格。
- 支持 SSR 開(kāi)箱即用。通過(guò)在構(gòu)建時(shí)將應(yīng)用預(yù)渲染為 HTML，用戶(hù)可以在加載任何 JS 之前看到內(nèi)容。
使用
vite-pages 默認(rèn)提供了三種模板，可以選擇初始化app(應(yīng)用)、lib(組件庫(kù))、lib-monorepo
可以通過(guò)命令創(chuàng)建一個(gè)自己的初始倉(cāng)庫(kù)
- npm init vite-pages [倉(cāng)庫(kù)名] --template [模板名]
我們執(zhí)行 npm init vite-pages library-demo --template lib 生成了一個(gè)典型的 Vite 結(jié)構(gòu)的項(xiàng)目，有熟悉的 vite.config.ts、pages 文件夾等
該插件所有明確的依賴(lài)包作用：
- @mdx-js/mdx MDX的實(shí)現(xiàn)
- @mdx-js/react 作為 MDX 的 React 實(shí)現(xiàn)。
- vite-plugin-mdx Vite 支持 MDX 的插件
- vite-plugin-react-pages 文檔插件核心實(shí)現(xiàn)
- vite-pages-theme-doc 官方的文檔主題。依賴(lài) react-router-dom ^5.0.0 版本
pages 目錄為文檔入口。文件式路由約定用 $ 符號(hào)的文件名結(jié)尾來(lái)識(shí)別為一個(gè)文檔頁(yè)面。
.ts|.tsx|.js|.jsx|.md|.mdx 只要 $ 是擴(kuò)展名前的最后一個(gè)字符，所有文件擴(kuò)展名都有效。
pages 目錄中還存在一個(gè)特殊的入口 _theme.tsx 用來(lái)配置當(dāng)前文檔的主題，vite-pages 默認(rèn)使用了 vite-pages-theme-doc 官方主題。如果自定義需求不大，可以通過(guò)配置官方主題的參數(shù)來(lái)實(shí)現(xiàn)常規(guī)的功能。比如配置 logo、頂部鏈接、左側(cè)菜單等。
我們來(lái)看看首頁(yè)文檔代碼
- ---
- title: 首頁(yè)
- ---
- import README from '../README.md'
- <README />
引入了 README.md 文檔作為首頁(yè)內(nèi)容，在 MDX 里，文檔和組件契合得相當(dāng)完美。
接下來(lái)新建一個(gè)文檔，粘貼一篇之前寫(xiě)過(guò)的主題
菜單名稱(chēng)會(huì)優(yōu)先使用 md 文件中的一級(jí)標(biāo)題，否則使用文件名。也可以在 md 文件的首行加入以下代碼設(shè)置：
- ---
- title: mac-scrollbar
- group: components
- subGroup: general
- ---
group 一級(jí)分組，會(huì)顯示在頭部列表區(qū)域;subGroup 二級(jí)分組，會(huì)將左側(cè)菜單分組顯示。
可以通過(guò) _theme.tsx 更改分組名和分組順序
- sideNavs: (ctx) => {
- return defaultSideNavs(ctx, {
- groupConfig: {
- components: {
- general: {
- label: '通用',
- order: 1,
- },
- dataRecord: {
- label: '數(shù)據(jù)錄入',
- order: 2,
- },
- },
- },
- });
- };
用它寫(xiě)文檔體驗(yàn)相當(dāng)不錯(cuò)，markdown 主題默認(rèn)自帶 github 樣式，排版清晰。熱更新做得非常棒，更改后即時(shí)就能看到效果。
接下來(lái)我們用它來(lái)做一個(gè)組件看看效果如何，做一個(gè)最基礎(chǔ)的按鈕組件
首先定義組件類(lèi)型：
- interface ButtonProps extends React.HTMLAttributes<HTMLButtonElement> {
- /**
- * 類(lèi)型
- * @defaultValue 'default'
- */
- type?: 'primary' | 'default' | 'text';
- /**
- * 尺寸
- * @defaultValue 'middle'
- */
- size?: 'large' | 'middle' | 'small';
- /**
- * 加載狀態(tài)
- * @defaultValue false
- */
- loading?: boolean;
- }
簡(jiǎn)單實(shí)現(xiàn)：
- import React from'react';
- import { ButtonProps } from'./types';
- import styles from'./style.module.css';
- const Button = ({ className, type, ...props }: ButtonProps) => {
- return (
- <button
- {...props}
- className={[styles.button, type === 'primary' && styles.primary, className].filter(Boolean).join(' ')}
- />
- );
- };
- exportdefault Button;
接著寫(xiě)一些 Demo
- /**
- * @title 基本按鈕
- * @description 一個(gè)很普通的按鈕
- */
- import React from'react';
- import { Button } from'my-lib';
- const Demo1 = () => {
- return<Button>按鈕</Button>;
- };
- exportdefault Demo1;
最后，在文檔中引入這些 Demo
- ---
- title: Button
- subGroup: general
- ---
- # Button
- 一個(gè)簡(jiǎn)單的按鈕組件
- <Demo src="./demos/demo1.tsx" />
- <Demo src="./demos/demo2.tsx" />
看看效果：
用它來(lái)調(diào)試組件相當(dāng)省心，調(diào)試完成等于文檔也寫(xiě)好了，還有自動(dòng)提取的代碼演示，做到了開(kāi)箱即用。
組件很重要的一部分是 API 文檔，要是能自動(dòng)從 typescript 注釋中提取就好了。沒(méi)錯(cuò)，vite-pages 支持了這項(xiàng)功能。
只需要在 MDX 中引入 TsInfo 組件，并設(shè)置類(lèi)型地址和名稱(chēng)：
- <TsInfo src="./types.ts" name="ButtonProps" />
將 ts 類(lèi)型提取出一個(gè)表格，能識(shí)別必填/描述/默認(rèn)值等。有了這個(gè)功能就不用擔(dān)心文檔和代碼割裂的問(wèn)題了
目前這個(gè)插件官方主題自帶趨向于組件文檔模式，基本功能齊全，沒(méi)有多余花哨的功能。如果想實(shí)現(xiàn)組件在線編輯預(yù)覽的話，可以 fork vite-pages-theme-doc 這個(gè)庫(kù)，然后可以改為自己想要的樣式，添加 react-live 支持在線實(shí)時(shí)編輯預(yù)覽。
官方默認(rèn)沒(méi)有提供博客主題。自己實(shí)現(xiàn)不難，因?yàn)?vite-plugin-react-pages 不渲染任何 DOM 節(jié)點(diǎn)，一切渲染相關(guān)都可以從 vite-pages-theme-doc 這個(gè)庫(kù)中修改。
小提示
總結(jié)當(dāng)前使用情況來(lái)看，使用了該插件會(huì)使 Vite 自動(dòng)依賴(lài)預(yù)構(gòu)建失效。你需要手動(dòng)將 node_modules 中的包添加到 optimizeDeps.include 中。比如 vite-pages-theme-doc 、lodash 等，否則會(huì)出現(xiàn)打開(kāi)頁(yè)面的時(shí)候重復(fù)刷新的情況。
github: https://github.com/vitejs/vite-plugin-react-pages
社區(qū)的主題實(shí)現(xiàn)：https://github.com/Codpoe/vite-pages-theme-press
