基于vite的组件文档编写神器，快速省心_0

现在Vite的生态在逐渐完善，今天给大家介绍一款React组件/应用文档编写神器：vite-plugin-react-pages是目前主流的构建文档站点方式：Gatsby-以GraphQL为核心，功能相当齐全，插件生态丰富。但学习曲线很高(React)Docusaurus-公司出品的Meta。功能强大，类似于Gatsby(React)dumi-UmiJS生态中的组件开发文档工具(React)Nextra-基于Next.js的静态站点生成器。(React)VuePress-包含一个Vue驱动的主题系统和插件API，另一部分是为编写技术文档优化的默认主题(Vue)VitePress-对VuePress做了很多改进。VitePress旨在降低当前VuePress的复杂性，并从其极简主义的根源重新开始。(Vue)除了VitePress，其他的都是用Webpack作为开发服务器。一个只有几页的简单文档站点，启动开发服务器所花费的时间变得难以忍受。即使是HMR更新也可能需要几秒钟才能反映在浏览器中。Vite的出现很好地解决了这些问题：近乎即时的服务器启动，只编译服务页面的按需编译，以及闪电般快速的HMR。作为基于Vite的文档解决方案，VitePress仅支持Vue。翻了翻Vite的官方库列表，偶然发现了一个只有100多星的文档解决方案vite-plugin-react-pages。抱着试水的心态开始体验，发现还是蛮好用的。只是很少有人知道。现在，让我们从用户的角度来分析一下它的实用功能。特性vite-plugin-react-pages(vite-pages)是一个基于vite的React应用框架。它适用于：博客站点组件库或产品的文档站点React组件的演示演示它提供了许多功能来帮助开发人员快速构建ReactApp：出色的开发体验。非常快速地启动本地开发服务器，即使有很多页面。HMR与React和MDX配合使用，因此您可以在编辑代码时获得有关更新的即时反馈。基于文件系统的路由。通过遵循简单的文件系统路由约定，可以轻松地创建、定位和开发页面。还可以配置vite-pages如何查找页面文件，以便支持具有任何文件结构的项目。支持MDX。可以使用“普通React”或MDX编写内容。“plainReact”和Markdown的灵活组合，更具可读性和易于编辑。强大的主题定制。vite-pages本身不渲染任何特定的DOM节点。使用默认的官方主题库，自己创建一个主题也很容易，可以自定义页面上的任何内容。基于页面的自动代码拆分。根据访问需要只加载当前页面数据。支持组件和代码预览。看到组件的功能后，就可以通过代码看看组件是如何使用的。支持打字稿类型提取。将typescript的类型定义和注释生成为组件API文档表。开箱即用地支持SSR。通过在构建时将您的应用程序预呈现为HTML，用户可以在加载任何JS之前看到内容。使用vite-pages默认提供三个模板，可以选择初始化app（应用）、lib（组件库），lib-monorepo可以通过命令npminitvite-pages[仓库名]--template[模板]创建自己的初始仓库name]我们执行npminitvite-pageslibrary-demo--templatelib生成一个具有典型Vite结构的项目，具有熟悉的vite.config.ts、pages文件夹和插件的所有显式依赖项。功能：@mdx-js/mdxMDX实现@mdx-js/react是MDX的React实现。vite-plugin-mdxvite支持MDX插件vite-plugin-react-pages文档插件核心实现vite-pages-theme-doc官方文档主题。依赖react-router-dom^5.0.0版本pages目录是文件入口。文件样式路由约定在文件名末尾使用$符号来标识文档页面。.ts|.tsx|.js|.jsx|.md|.mdx所有文件扩展名都有效，只要$是扩展名前的最后一个字符。pages目录下还有一个专门的入口_theme.tsx用来配置当前文档的主题，vite-pages默认使用vite-pages-theme-doc的官方主题。如果定制需求不大，可以通过配置官方主题的参数实现常规功能。比如配置logo，顶部链接，左侧菜单等。我们看一下首页文档代码---title:Homepage---importREADMEfrom'../README.md'引入了README.md文档作为主页的内容。在MDX中，文档和组件完美契合。接下来新建一个文件，粘贴一个之前写好的主题菜单名，md文件中的一级标题优先使用，否则使用文件名。也可以在md文件第一行加入如下代码设置：---title:mac-scrollbargroup:componentssubGroup:general---grouplevel一级分组会显示在headlist区域；subGrouplevel二级分组会在左侧显示菜单分组显示。您可以通过_theme.tsxsideNavs:(ctx)=>{returndefaultSideNavs(ctx,{groupConfig:{components:{general:{label:'General',order:1,},dataRecord:{label:'数据输入',order:2,},},},});};用它写文档的体验还是不错的，markdown主题默认自带github风格，布局清晰。热更新做的很好，改完马上就能看到效果。接下来，我们用它来制作一个组件，看看它是如何工作的。要制作一个基本的按钮组件，首先要定义组件类型：interfaceButtonPropsextendsReact.HTMLAttributes{/***Type*@defaultValue'default'*/type?:'primary'|'default'|'text';/***size*@defaultValue'middle'*/size?:'large'|'middle'|'small';/***加载状态*@defaultValuefalse*/loading?:boolean;}简单实现：importReactfrom'react';import{ButtonProps}from'./types';importstylesfrom'./style.module.css';constButton=({className,type,...props}:ButtonProps)=>{return();};exportdefaultButton;然后写一些Demo/***@titlebasicbutton*@description一个很普通的button*/importReactfrom'react';import{Button}from'my-lib';constDemo1=()=>{returnButton;};exportdefaultDemo1;最后在文档中介绍这些Demo---title:ButtonsubGroup:general---#ButtonAsimplebuttoncomponent看效果：用它调试组件还是挺省心的，调试完成意味着文档也写好了是的，还有自动提取代码的演示。开箱即用组件的一个重要部分是API文档。如果能自动从打字稿注释中提取出来就好了。是的，vite-pages支持这个功能。只需要在MDX中引入TsInfo组件，并设置类型地址和名称：/默认值等待。有了这个功能，你就不用担心文档和代码分离的问题了。目前该插件官方主题趋向于组件文档模式，基本功能齐全，没有多余的花哨功能。如果想实现组件的在线编辑和预览，可以fork库vite-pages-theme-doc，然后改成自己想要的样式，加上react-live支持在线实时编辑和预览。默认没有提供官方博客主题。自己实现并不难，因为vite-plugin-react-pages不渲染任何DOM节点，所有与渲染相关的都可以从vite-pages-theme-doc库中修改。Tips总结目前的使用情况，使用该插件会导致Vite自动依赖pre-build失效。您需要手动将包从node_modules添加到optimizeDeps.include。如vite-pages-theme-doc、lodash等。否则打开页面会出现反复刷新。github:https://github.com/vitejs/vite-plugin-react-pages社区主题实现:https://github.com/Codpoe/vite-pages-theme-press