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