一款基於 vite 的元件文件編寫神器,又快又省心

語言: CN / TW / HK

theme: juejin highlight: agate


現在 Vite 的生態逐漸完善,今天給大家介紹一款 React 的元件/應用文件編寫神器: vite-plugin-react-pages

目前主流搭建文件站點的方式:

  1. Gatsby - 以 GraphQL 為核心,功能相當完善,外掛生態豐富。但學習曲線高(React)
  2. Docusaurus - Meta 公司出品。功能強大,與 Gatsby 相似(React)
  3. dumi - 一款 UmiJS 生態中的元件開發文件工具(React)
  4. Nextra - 一個基於 Next.js 的靜態站點生成器。(React)
  5. VuePress - 包含由 Vue 驅動的主題系統和外掛 API,另一個部分是為書寫技術文件而優化的預設主題(Vue)
  6. VitePress - 對 VuePress 進行了不少的改進。VitePress 旨在降低當前 VuePress 的複雜性,並從其極簡主義的根源重新開始。(Vue)

除了 VitePress 之外,其他都是用 Webpack 作為開發伺服器。一個只有幾頁的簡單文件站點啟動開發伺服器所花費的時間變得難以忍受。即使是 HMR 更新也可能需要幾秒鐘才能反映在瀏覽器中。Vite 的出現很好地解決了這些問題:近乎即時的伺服器啟動、僅編譯所服務頁面的按需編譯以及閃電般快速的 HMR

作為 Vite 的基礎上的文件方案, VitePress 只支援 Vue

翻閱 Vite 的官方庫列表,偶然發現了一款 star 數量僅 100 多的文件解決方案 vite-plugin-react-pages。開始用試試水的心態去去體驗一把,結果發現相當好用。就是知道的人太少了。現在,我們從使用者的角度去解析它好用的功能。

特性

vite-plugin-react-pages(vite-pages) 是一個由 vite 提供支援的 React 應用程式框架。它非常適合:

  • 部落格網站
  • 元件庫或產品的文件站點
  • React 元件的 Demo 演示

它提供了許多幫助開發人員快速構建 React App 的功能:

  • 很棒的開發體驗。即使有很多頁面,也可以極速啟動本地開發伺服器。HMR 適用於 ReactMDX,因此可以在編輯程式碼時獲得即時的更新反饋。
  • 基於檔案系統的路由。通過遵循簡單的檔案系統路由約定,可以輕鬆建立、定位和開發頁面。也可以配置 vite-pages 如何查詢頁面檔案,以便支援任何檔案結構的專案。
  • 支援 MDX。可以使用 “普通 React” 或 MDX 編寫內容。“普通 React” 與 Markdown 靈活組合,更具可讀性和易於編輯。
  • 強大的主題定製vite-pages 本身不渲染任何具體的 DOM 節點。使用預設的官方主題庫,也可以很容易自己建立一個主題,可以自定義頁面上的任何內容。
  • 基於頁面的自動程式碼拆分。只根據訪問需要載入當前的頁面資料。
  • 支援元件與程式碼預覽。在看到元件功能之後,可以通過程式碼檢視元件使用方式。
  • 支援 typescript 型別提取。將 typescript 的型別定義和註釋生成為元件 API 文件表格。
  • 支援 SSR 開箱即用。通過在構建時將應用預渲染為 HTML,使用者可以在載入任何 JS 之前看到內容。

使用

vite-pages 預設提供了三種模板,可以選擇初始化app(應用)、lib(元件庫)、lib-monorepo

可以通過命令建立一個自己的初始倉庫

bash npm init vite-pages [倉庫名] --template [模板名]

我們執行 npm init vite-pages library-demo --template lib 生成了一個典型的 Vite 結構的專案,有熟悉的 vite.config.tspages 資料夾等

該外掛所有明確的依賴包作用:

  • @mdx-js/mdx MDX的實現
  • @mdx-js/react 作為 MDXReact 實現。
  • vite-plugin-mdx Vite 支援 MDX 的外掛
  • vite-plugin-react-pages 文件外掛核心實現
  • vite-pages-theme-doc 官方的文件主題。依賴 react-router-dom ^5.0.0 版本

pages 目錄為文件入口。檔案式路由約定用 $ 符號的檔名結尾來識別為一個文件頁面。

.ts|.tsx|.js|.jsx|.md|.mdx 只要 $ 是副檔名前的最後一個字元,所有副檔名都有效。

| 檔案路徑 | 頁面 url | | :-------------------------------- | :------------------- | | index$.tsx | / | | $.tsx (與 index$.tsx 效果相同) | / | | page-one$.tsx | /page-one | | page-two$.md | /page-two | | dir-name/page-three$.mdx | /dir-name/page-three | | dir-name/[id]/index$.tsx | /dir-name/:id |

pages 目錄中還存在一個特殊的入口 _theme.tsx 用來配置當前文件的主題,vite-pages 預設使用了 vite-pages-theme-doc 官方主題。如果自定義需求不大,可以通過配置官方主題的引數來實現常規的功能。比如配置 logo、頂部連結、左側選單等。

我們來看看首頁文件程式碼

```md

title: 首頁

import README from '../README.md'

```

引入了 README.md 文件作為首頁內容,在 MDX 裡,文件和元件契合得相當完美。

1.png

接下來新建一個文件,貼上一篇之前寫過的主題

2.png

選單名稱會優先使用 md 檔案中的一級標題,否則使用檔名。也可以在 md 檔案的首行加入以下程式碼設定:

```

title: mac-scrollbar group: components subGroup: general


```

group 一級分組,會顯示在頭部列表區域;subGroup 二級分組,會將左側選單分組顯示。

可以通過 _theme.tsx 更改分組名和分組順序

js sideNavs: (ctx) => { return defaultSideNavs(ctx, { groupConfig: { components: { general: { label: '通用', order: 1, }, dataRecord: { label: '資料錄入', order: 2, }, }, }, }); };

用它寫文件體驗相當不錯,markdown 主題預設自帶 github 樣式,排版清晰。熱更新做得非常棒,更改後即時就能看到效果。

接下來我們用它來做一個元件看看效果如何,做一個最基礎的按鈕元件

首先定義元件型別:

typescript export interface ButtonProps extends React.HTMLAttributes<HTMLButtonElement> { /** * 型別 * @defaultValue 'default' */ type?: 'primary' | 'default' | 'text'; /** * 尺寸 * @defaultValue 'middle' */ size?: 'large' | 'middle' | 'small'; /** * 載入狀態 * @defaultValue false */ loading?: boolean; }

簡單實現:

```tsx import React from 'react'; import { ButtonProps } from './types'; import styles from './style.module.css';

const Button = ({ className, type, ...props }: ButtonProps) => { return ( ; };

export default Demo1; ```

最後,在文件中引入這些 Demo

```md

title: Button subGroup: general


Button

一個簡單的按鈕元件

```

看看效果:

3.gif

用它來除錯元件相當省心,除錯完成等於文件也寫好了,還有自動提取的程式碼演示,做到了開箱即用

元件很重要的一部分是 API 文件,要是能自動從 typescript 註釋中提取就好了。沒錯,vite-pages 支援了這項功能。

只需要在 MDX 中引入 TsInfo 元件,並設定型別地址和名稱:

tsx <TsInfo src="./types.ts" name="ButtonProps" />

4.png

ts 型別提取出一個表格,能識別必填/描述/預設值等。有了這個功能就不用擔心文件和程式碼割裂的問題了

目前這個外掛官方主題自帶趨向於元件文件模式,基本功能齊全,沒有多餘花哨的功能。如果想實現元件線上編輯預覽的話,可以 fork vite-pages-theme-doc 這個庫,然後可以改為自己想要的樣式,新增 react-live 支援線上實時編輯預覽。

官方預設沒有提供部落格主題。自己實現不難,因為 vite-plugin-react-pages 不渲染任何 DOM 節點,一切渲染相關都可以從 vite-pages-theme-doc 這個庫中修改。

小提示

總結當前使用情況來看,使用了該外掛會使 Vite 自動依賴預構建失效。你需要手動將 node_modules 中的包新增到 optimizeDeps.include 中。比如 vite-pages-theme-doclodash 等,否則會出現開啟頁面的時候重複重新整理的情況。

github: https://github.com/vitejs/vite-plugin-react-pages

社群的主題實現:https://github.com/Codpoe/vite-pages-theme-press

今年輸出的文章

可以加 React 群一起交流學習進步。公眾號: 前端星辰