Vue3 enterprise-level elegance in practice - component library framework - 12 release of open source component library

The previous 11 articles were used to share the development, construction and release of the component library project of the complete four-piece set (component library, documentation, example, cli) based on vue3 and Monorepo. This article is an extension of these 11 articles - how to publish to GitHub and how to quickly use GitHub to publish component library documents. In this way, Elegant Brother's "Component Library Framework" series forms a closed loop: from development to open source. Before starting this article, please register a GitHub account and log in.

1 CommitGitHub

1.1 Create Repository

After logging in to GitHub, click "+" - "New repository" in the upper right corner to create a Repository, as shown below:

After entering the create warehouse page, fill in the warehouse name (regarding the warehouse name, Elegant Brother is accustomed to using the local project name), and click the "Create repository" button at the bottom of the page:

After the warehouse is created, you will enter the warehouse page, where it is clearly stated how to submit local code to the GitHub warehouse.

1.2 Push code

Enter the project root directory in the command, and execute the following commands in order to submit the code to the GitHub repository created above.

1. Initialize the local Git repository:

git init

2. Add files to commit to git:

git add .

3. Submit the code to the local repository:

git commit -m 'feat: 初始化组件库工程'

4. Set up the master branch:

git branch -M main

5. Add a remote warehouse. This line of command can be seen from the page after the warehouse is successfully created above:

git remote add origin [email protected]:HeroCloudy/yyg-demo-ui.git

6. Push the code to the GitHub repository:

git push -u origin main

This will submit the local code to GitHub. Refresh the warehouse page, as shown below:

If there are subsequent modifications to the code, first use git commit to submit it to the local warehouse, and then use the git push command to push it to GitHub.

2 Publish component library documentation

The code has been released on GitHub. Next, we hope to make full use of GitHub's resources and publish the packaged document of the component library to GitHub so that users can directly access the document.

GitHub provides a capability pages , through which we can publish static HTML resources to GitHub and support access to web pages in the form of HTTP.

The implementation idea is as follows:

1. Build component library documentation;
2. Submit and push the built component library document ( ./docs/.vitepress/dist ) to another branch of the warehouse;
3. Configure GitHub Pages to point to the new branch above.

2.1 Build component library documentation

We previously configured the build command of the component library document:

pnpm run docs:build

Wait for the build to complete, and you will see that the packaged content is located in the ./docs/.vitepress/dist directory.

2.2 Push to github new branch

After the document is built, it needs to be submitted to a new branch. If done manually, it will be more cumbersome. Brother Yaya recommends using an npm tool to help us complete this operation - gh-pages .

Install gh-pages in the project root directory :

pnpm install gh-pages -D -w

Next, you can use gh-pages to submit the specified directory to a new branch of github (gh_pages branch):

gh-pages -d docs/.vitepress/dist

After a while, the console will prompt Published , which means the release is successful. At this time, you can look at the branches of the warehouse:

First execute git fetch to pull the latest branch information on GitHub, and then execute git branch -a to view all local and remote branches. The output is as follows:

You can see that there is an additional remote branch named gh-pages . We can also see this branch on the GitHub warehouse homepage:

To recap, the above operation involves two steps:

1. Package component library documentation
2. Push the packaged content of the document to the gh-pages branch.

We can add a new script in package.json in the project root directory to combine the above two operations:

"scripts": {
    
    
  ...
  "docs:deploy": "pnpm run docs:build && gh-pages -d docs/.vitepress/dist",
  ...
},

When later modifying the content of the component library document, you only need to execute pnpm run docs:deploy .

2.3 Configure GitHub Pages

1) Click the Settings button on the warehouse homepage to enter the warehouse settings page

2) Click pages on the left side of the settings page to enter the GitHub Pages page. On this page, you can see that the gh-pages branch is configured for us by default , and it also tells us the access address:

3) When you access the path in the browser, you will find that the display is abnormal. This is because the context path (BaseUrl) configured in the component library document module is different from the real context path.

2.4 Component library document context path differentiates environment

Finally, we need to modify the context path of the component library. If it is a simple process, just modify the value of the base attribute of the exported object in docs/.vitepress/config.ts . The context path in github pages is: /yyg-demo-ui/ , so you only need to simply change base: '/' to base: '/yyg-demo-ui/' . But in this case, the access path also needs to carry this context http://localhost:3100/yyg-demo-ui when developing locally .

So how to use / for local development and /yyg-demo-ui/ for packaging and construction ? It only takes the following three steps to achieve:

1) Add the development dependency minimum in the docs module , which is used to extract parameters in the command:

pnpm install minimist -D

2) Modify the build command in the docs module and add a build parameter to the command:

"scripts": {
	...
	"build": "vitepress build --build",
	...
},

3) Determine whether the current running mode is dev or build in docs/.vitepress/config.ts , and specify the value of base based on the judgment result :

import minimist from 'minimist'
....

const argv = minimist(process.argv.slice(2))
const build = argv.build || false

export default defineConfig({
    
    
  ...
  base: build ? '/yyg-demo-ui/' : '/',
  ...
})

In this way, we can specify different context paths according to different running modes.

Submit the code in the project root directory and re-execute pnpm run docs:deploy . Wait for the component library document to be packaged and published to be displayed as Published . Then refresh the browser to display the component library document page. If the display is still abnormal, it may be due to network and cache issues. Please refresh violently in a few minutes and try again:

At this point, we have completed the open source of the component library, submitted it to GitHub, and used GitHub Pages to access the documentation of the component library. There are many advanced operations on GitHub, such as using GitHub for CI/CD, Action runner, etc. It can help us more automatically realize many operations. You can learn more about it if you have nothing to do.

Thank you for reading this article. If this article has given you a little help or inspiration, please support me three times to learn more about Gongwei account "Brother Elegant Programmer".