Vite plugin-React-Pages is one of the most popular tools for creating React components and applications

At present, the mainstream way to build a document site:

  1. Gatsby – With GraphQL as the core, it has quite complete functions and rich plug-in ecology. But the learning curve is high.
  2. Docusaurus-meta. Powerful, Like Gatsby (React)
  3. Dumi – A component development documentation tool in the UmiJS ecosystem (React)
  4. Nextra – a static site generator based on next.js. (React)
  5. VuePress – contains a VUE-driven theme system and plug-in API, another part is a default theme optimized for writing technical documentation (Vue)
  6. VitePress – a number of improvements to VuePress. VitePress aims to reduce the complexity of current VuePress and start over from its minimalist roots. (Vue)

With the exception of VitePress, all use Webpack as the development server. The time it takes to start a development server for a simple documentation site of a few pages becomes unbearable. Even HMR updates can take a few seconds to show up in the browser. The advent of Vite solves these problems nicely: near-instant server startup, on-demand compilation that only compiles the pages it serves, and lightning-fast HMR.

As a Vite based documentation solution, VitePress only supports Vue.

Browsing through the official library list of Vite, I came across a document solution called Vite-plugin-React-Pages with just over 100 star files. Start experimenting with the water mentality to try it out, turns out to be quite useful. It’s just that too few people know. Now, let’s take a look at what works from the user’s point of view.

features

Viet-plugin-react-pages (viet-Pages) is a react application framework supported by Vite. It’s perfect for:

  • The blog site
  • A documentation site for a component library or product
  • ReactThe component’sDemodemo

It provides a number of features to help developers quickly build React apps:

  • Great development experience. Even if you have a lot of pages, you can quickly start up your local development server. HMR is suitable for theReact 和 MDX, so you can get immediate feedback on updates as you edit code.
  • File system-based routing. Pages can be easily created, located, and developed by following simple file system routing conventions. You can also configurevite-pagesHow to find page files in order to support any file structure of the project.
  • supportMDX. You can use “Plain React” orMDXWrite content. “Ordinary React” vsMarkdownFlexible combination, more readable and easy to edit.
  • Powerful theme customization.vite-pagesDoesn’t render anything concrete itselfDOMNode. Using the default official theme library, it’s also easy to create a theme of your own, and you can customize anything on the page.
  • Automatic page-based code splitting. Load the current page data only as needed for access.
  • Support for component and code preview. Once you see what the component does, you can look at the code to see how it is used.
  • supporttypescriptType extracting. willtypescriptType definitions and annotations for the component API documentation form.
  • Support SSR out of the box. By pre-rendering the application to HTML at build time, the user can see the content before loading any JS.

use

Viet-pages provides three templates by default, and you can choose to initialize app (application), lib (component library), and lib-monorepo

You can create your own initial repository by command

NPM init template-pagesCopy the code

We execute NPM init vite-pages library-demo –template lib to generate a typical vite structure project, with familiar vite. Config. ts, pages folder, etc

All explicit dependency packages for this plug-in:

  • @mdx-js/mdx MDXThe implementation of the
  • @ MDX – js/react asMDX 的 ReactThe implementation.
  • Vite plugin – MDX vite supportMDXThe plug-in
  • Vite-plugin-react-pages document plugin core implementation
  • Viet-pages-theme-doc Specifies the official document theme. Rely onreact-router-dom^ 5.0.0 version

The Pages directory is the document entry. The file routing convention identifies a document page with the $sign at the end of the file name.

. Ts |. TSX |. Js |. JSX. | | md. MDX as long as the $is the last one character at a time, before the extension all names effective file extension.

The file path The page url
index$.tsx /

. t s x (with i n d e x Benchmark (with the index .tsX has the same effect)		 /
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

TSX is used to configure the theme of the current document. By default, viet-pages uses the official theme of viet-pages-theme-doc. If customization is not required, you can configure the parameters of the official theme to implement general functionality. For example, configure logos, top links, left menus, and so on.

Let’s take a look at the home page document code

---
Title: - home pageimport README from '.. /README.md'<README />
Copy the code

With the introduction of readme.md documents as home page content, documents and components fit perfectly in MDX.

Next, create a new document and paste a topic you’ve already written about

The first level title in the MD file is preferred for menu names, otherwise the filename is used. You can also add the following code Settings to the first line of the MD file:

---
title: mac-scrollbar
group: components
subGroup: general
---
Copy the code

Group Indicates the level 1 group, which is displayed in the header list area. SubGroup Indicates the level 2 grouping. The menu on the left is displayed in groups.

You can change the group name and group order by using _theme.tsx

sideNavs: (ctx) = > {
  return defaultSideNavs(ctx, {
    groupConfig: {
      components: {
        general: {
          label: 'general'.order: 1,},dataRecord: {
          label: 'Data entry'.order: 2,},},},}); };Copy the code

It’s a great experience for writing documents, and markdown themes come with github style by default, with clear typography. Hot updates do a great job of making changes that are immediately visible.

Now let’s make a component out of it and see what it looks like, make a basic button component, okay

First define the component type:

export interface ButtonProps extends React.HTMLAttributes<HTMLButtonElement> {
  /** * type *@defaultValue 'default'
   */
  type? :'primary' | 'default' | 'text';
  /** * size *@defaultValue 'middle'
   */size? :'large' | 'middle' | 'small';
  /** * Load status *@defaultValue false* /loading? :boolean;
}
Copy the code

Simple implementation:

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(' ')} / >
  );
};

export default Button;
Copy the code

And then I’ll write some demos

/ * * *@title Basic buttons@description A very ordinary button */

import React from 'react';
import { Button } from 'my-lib';

const Demo1 = () = > {
  return <Button>button</Button>;
};

export default Demo1;
Copy the code

Finally, introduce these demos into your documentation

---
title: Button
subGroup: general
---

# ButtonA simple button component<Demo src="./demos/demo1.tsx" />

<Demo src="./demos/demo2.tsx" />
Copy the code

Look at the results:

Debugging components is a lot easier, documentation is written when debugging is done, and there are automatically extracted code demos, right out of the box.

An important part of a component is the API documentation, which would be nice if it could be extracted automatically from typescript annotations. True, Viet-Pages supports this feature.

Just import the TsInfo component in the MDX and set the type address and name:

<TsInfo src="./types.ts" name="ButtonProps" />
Copy the code

Extract the TS type into a table that recognizes required/description/default values, etc. With this feature, you don’t have to worry about splitting documents and code

At present, the official theme of this plug-in tends to be a component document mode, the basic function is complete, no extra fancy functions. If you want to preview your components online, fork the waite-pages-theme-doc library. Then you can change it to your own style and add react-Live support for live preview editing online.

There is no official blog theme provided by default. This is not difficult to implement yourself, because viet-plugin-react-pages does not render any DOM nodes, and everything related to rendering can be modified from the viet-pages-theme-doc library.

tip

Based on current usage, using this plugin disables Vite’s automatic dependency prebuild. You need to manually add packages from node_modules to optimizedeps.include. For example, viet-pages-theme-doc and Lodash will refresh the page repeatedly when it is opened.

Making: github.com/vitejs/vite…

Thematic implementation of the community: github.com/Codpoe/vite…

Articles exported this year

Use the React group to communicate and learn. Public number: Front star

  • These can become Web syntax specifications, compulsive to watch
  • How to write a more elegant React component
  • How to write a more elegant React component – code structure
  • 2021 year-end summary, an 8 – year – old front-end where to go
  • […undefined] what is the result of the implementation?
  • React Boutique component: Mac-ScrollBar
  • We migrated from UmiJS to Vite
  • Forget useCallback, we have a better way
  • How to write more elegant code – JavaScript text
  • React Hooks performance optimized for correct posture