The preface

This series of articles will be updated as the author progresses.

The expected contents are as follows:

Build your React UI component library:

A: from V0.0.0 to V0.0.1

(two) : build the home page

(III) Documentation (this article)

(four) : Clean the details

(V) : promotion, publicity and iteration

<= to be continue =

This is where I can access my component library: BB-color

And NPM address: bb-color

convention

  1. This series covers every step, every file, and every update as much as possible.
  2. In this series of articles, the entire project is based on official sourcescreat-react-appWith the React build, everything will be developed using the latest library version.
    • The create – react – app v2.1.1
    • The react v16.7.0
    • Webpack v4.19.1
    • babel 7+
    • The node v10.15.0
    • Docz v0.13.7

You’re supposed to know

  • React
  • Will use the Git
  • Basic knowledge of JavaScript, CSS, etc


The text start

The starting point

The UI component library is all about documentation, and that’s the most important thing. We will use DOCZ to assist us in document development.

Note 1:

Docz can quickly create React UI library documents for use and demonstration. It uses MDX, an extension of the Markdown syntax, to write documents. It currently only supports React. More content can be found on Github and its official documentation


The preparatory work

Run the following command to install the required dependencies

npm install --save-dev docz docz-theme-default docz-plugin-css @emotion/core
Copy the code

Note 2:

Docz: A core part of docZ, a must

Docz-theme-default: specifies the default docz theme. This parameter is mandatory

Docz-plugin-css: An additional plugin to use CSS in docZ, not required if CSS is not required

Emotion/Core: Document dependent, required


After the installation is complete, modify our package.json

// package.json{..."scripts": {..."docz:dev": "docz dev"."docz:build": "docz build"}... }Copy the code


Written document

We create home.mdx in SRC/Components

A: Yes.

It does not have to be created in SRC.

Note that you don’t need to follow any strict file architecture. You can just create your .mdx files anywhere in your project.

Docz recognizes.mdx files anywhere, so you can write documents anywhere. You can also create another DOCZ folder to store your document files separately, but I recommend that you write according to the directory structure of our component, so that we can directly find the content we need in the subsequent modification.

// SRC /components/home.mdx -- name: homeroute: /
---

# Hello world

Hello, I'm a mdx file!
Copy the code

Then create button.mdx in SRC /components/button

// src/components/button/button.mdx

---
name: Button
route: /button
---

import { Playground, PropsTable } from 'docz'
import Button from './index.js'

# Button

<PropsTable of={Button} />

## Basic usage

<Playground>
 <Button>Click me</Button>
</Playground>
Copy the code

The documentation part of the writing ends here, and the configuration part comes next

Create doczrc.js in the root directory

// doczrc.js

import { css } from 'docz-plugin-css'

export default {
  title: 'BB Color'.description: 'A Design UI library for React'.plugins: [
    css({
      preprocessor: 'postcss'}})]Copy the code

When you’re done, the entire project directory looks like this

We then execute NPM run docz:dev through gitbash just as we did with NPM start

If there are no problems, you will see the following page

Congratulations, you have successfully built your own document. You can click on the left “home”, “Button” to see the specific content.

So far we’ve only done the very, very basics, and this article will only cover the basics of content building, leaving every detail and document to you and your creativity.


* Packaged export (optional)

NPM run docz:build and you’ll find your static files in.docz/dist. If you want to pack to another folder, you can configure it in doczrc.js

You can find the configuration here:

www.docz.site/introductio…

I’m going to leave it as it is.

This is what happens when you do the packaging

./. Docz /dist is the file we packed


Submit code

Before committing the code, modify.gitignore

// .gitignore. /.docz ...Copy the code

This is followed by a normal commit

Git add. Git commit -m 'git push' -u origin masterCopy the code


Wait a minute! Yet!!!

After the code is submitted, the document page cannot be accessed, and we need to deploy our document code


The deployment code

The files we packaged are static files that we need to deploy separately.

You might want to create a doc file in Docs, put the dist file in doc, and access it directly through Github Pages, like the home page.

Unfortunately, this method is not feasible.

There’s a problem here. Docz is a packaged resource file that references the absolute path based on the root of the route.

For example, IF I start a local service under the docs/ path at http://127.0.0.1/, we can access docs/index.html normally. When we access the document page, the address is changed to http://127.0.0.1/doc and we can also access docs/doc/index.html but none of the resources will load because the referenced resources will be found in the root directory of the startup server (docs). Instead of looking in the relative path./docs/doc.

The site we generated via Github Pages was addressed like this: https://bb-color.github.io/BB-color/ couldn’t find the static files we needed at https://bb-color.github.io.


There are two ways to deploy our documentation code.

  1. Buy a server, domain name, push our code to the server, access from the domain name.
  2. Use Netlify to help us deploy.


Use Netlify for deployment

Netlify is a great simple tool that allows you to automatically deploy your application by running it from every push in a branch in seconds, and it’s free

Log in to Netlify using Github

After successful login, you will automatically jump to your home page and follow the instructions of the red arrow below.

Then simply select our component library file


And then there are three things to set up,

  • The first one is to pick the branch, so let’s just pick the Master

  • The second is to enter the build command, the document build command that we set up in package.json.

  • The third is to enter the path of the packaged file after executing the document build command. Since I didn’t change the path, enter the default.docz/dist.

Then click Deploy Site to deploy


It will deploy automatically during the first step in the figure below, just wait for the first step to complete.

After the deployment is complete, you will be able to access the deployed website under the red arrow. If you are not satisfied with the domain name, you can configure your own domain name at the yellow arrow.

We only need to set this up once, and Netlify will automatically deploy the latest code for us every time we submit it.


To submit again

Before submitting, modify our home page so that our home page jumps to our document page.

Git tag -a 'v0.0.3' -m '-m' git tag -a 'v0.0.3' -m '-m' -m '-m' -m '-m' -m '-m' -m '-m' -m '-m' -m '-m' -m '-mCopy the code


Congratulations, a UI component library with a home page and documentation!!


The end of the

I thought the three most important chapters in this series would take a long time to write, but I never expected to finish them so quickly. After all, THERE are other pressures forcing me to finish this part as soon as possible

Then chapters four and five are additional chapters, not as important as the first three, and they won’t be written so quickly. 2333

If there is anything inappropriate or missing, please point it out in the comments section and communicate rationally.

If need to be reproduced, please indicate the author and original address

Author: ParaSLee

Original text: juejin. Cn/post / 684490…