Writing in the front

This article may not teach you in detail how to make an open source component library, and the author is still exploring and learning, but it may give you some inspiration. This post is both shared and documented, and at the time of writing, it has been nearly a year since the author first started working on an open source project. A year ago I had no idea how to develop a component library and little knowledge of open source projects. With a no-learn attitude, I enlisted two friends and started Varlet development.

Varlet component library related links, hope to encourage and support

Github Repository Chinese document English document

Design background

At the beginning of the component library design, the author was not satisfied with the design style of the library used by the previous company, and had a plan to upgrade Vue3, hoping to have a more textual and stronger visual effect design style. However, since the company is not able to Design such a Design System, and there is no mobile end open source component library that meets the requirements in the market, the author has the idea of making a new component library by relying on some existing Design systems. However, the company is not very concerned about the idea of developing the component library. Without the support of the company, the author still hopes to implement his idea, so it gradually becomes a personal open source project.

Invite partners

Do an open source project must have their own trusted partners, avoid many of the functions of their own head to design, because everyone’s technology stack and technical thinking is not completely the same, even if you are very experienced, partners will see a lot of things you can’t see. If you are in business, invite your colleagues. If you’re an individual, invite a friend you trust, or go to the Nuggets and post a blog post to find someone who shares your interests.

Learn mainstream solutions together

After all, everything we do has to have a foundation, there are multiple learning objects, in the case of nothing, we need to learn the mainstream component library architecture scheme, We learned the architectural ideas of Vant, Vuetify, Element, Element-Plus, Material-UI, Muse-UI, and many other component libraries, and thought about the implementation as we went along.

Monorepo architecture

We adopted the unpacking architecture, mainly through Yarn Workspace and LerNA. The advantage is that we can make common dependencies into a package and publish them separately. In the process of building the component library, some practical tools can be produced at the same time, which also lays a foundation for the expansion of the later project. At the same time, Lerna has a perfect packet sending mechanism, so that we do not need to care too much about the dependency between packages. The component library is designed to be one of those sub-packages, so Varlet might not be just a component library in the future, but a solution as packages grow, and we’re actually exploring that.

Design System

First of all, the author does not recommend developing a component library without designing a system, because the design you come up with on your head will always be unreasonable. If the enterprise has its own ability to design a style or design system that is the best choice. If you’re unlucky like the author, you’d be better off with an open source, mature design system. For example, we chose Material Design. One of the author’s friends is also doing his own component library. He chose Vercel Design, and here is his Github repository.

Related tools

Building a component library requires a wide range of tools, and we consider that a mature component library should meet at least the following basic development requirements

  • Development environment, you need a service to debug code
  • Support on demand import, no one should want to fully import the component library
  • Component libraries are compiled and generatedumdandesmComponent code for a module
  • To build a development document, at least have a Chinese document explaining how the components work
  • Unit tests, you have to trust the code you write
  • For desktop and mobile component previews, do you want users to see what the components look like
  • Code formatting and standard detection tools, after all, is a team crime, no rules no fangyuan
  • With an automated documentation deployment and testing process, you can’t manually deploy documentation and tests for every release

So we decided to implement all of this ourselves, and pulled out a separate sub-package called Varlet-CLI, which is now also open source, greatly lowering the bar for developing component libraries. The user manual is here, and the specific implementation can go to our Github repository to see the source code

The development environment

Our development environment used Webpack5 and Webpack-dev-server to build an official document site, scanned the SRC directory based on our custom plug-in, extracted useful information and built the basic routing and document configuration. As for documentation, we compiled md files into vue Template String rendering in each routing module through varlet-Markdown-loader, making documentation easier.

Why not Vite

Say a word, when we are ready to start in October last year, Vite is not stable, there is no must in Vite as the reason for the development environment, may hereafter have the possibility of change, but we are still will energy to focus on more important things, for individual developers, reasonable arrangement of time to do more effective output is one of the most important. But for a new project, I think Vite should be the first choice because it’s really, really good

Component library compiler

Once we have a development environment in place, we also need to export our component code to UMD and ESM modules for the user to use. Instead of using rollup, we will choose a compiler that implements the component library ourselves. Compiled component is the core is to scan the entire directory, and what’s the format of the file with the corresponding compiler has been to him again, this is easy, your implementation can be added in the compilation process a lot of optimization, and is completely controllable freely, can generate we hope generated module structure, is convenient for us to achieve on-demand, introducing the fact proved, it is worth it.

Component prototyping and refactoring

When we started to develop components for specific scenarios, we would explain our own understanding of this component, and the person in charge of this component would take the lead to do prototype development, namely the draft. Since talk is cheap, we need to make a rough prototype and make specific implementation. When the prototype development was finished, we reviewed the prototype again and had in-depth discussions. Finally, the person in charge of the component would rewrite the component, determine the API, complete the documentation, complete the single test, and finally release. Don’t be afraid to rewrite and overturn, and don’t expect to hit the ground running. Here are some lessons we’ve learned over time.

Component unit test writing

In order to ensure component stability and reduce maintenance stress, each function needs to be fully unit tested. We used Jest + @vue/test-utils for testing. These two packages are also officially recommended by VUE. You then need to generate test reports using JEST and host them to Codecov, an open source test results presentation platform that allows you to visualize test results.

Component release

We follow the Semver semantic version specification, which is a pattern like 1(major version number).0(minor version number).0(revision number). Destructive updates move first, new features move second, and bug fixes move third. Most open source projects follow this specification, so we try not to play around with our version numbers. When you’re finished with a release and you’re unsure about what’s going to happen in the release, make sure to release the alpha version first and test it over and over in production. For projects that already have a large user base, there should be alpha, beta, RC and more prior releases for each update to provide reliability for the official release.

Document the deployment

Where documents are deployed is an issue, and for most people, there may not be the energy to maintain a static server. I recommend Gitee Pages and Github Pages, which help us host static resources and are free.

Git Actions automatic deployment and testing

As the number of contributors to a project grows, some contributors inevitably make process mistakes. For example, forgetting to run unit tests when submitting code, not trying to build the project in production mode, etc. To avoid errors, we need to do some procedural tasks when submitting code to git remote repository, which is often referred to as CI/CD or pipeline. For example, every time a new version is released, the document will inevitably need to be redeployed. It is too cumbersome to deploy the document manually each time. Git Actions can solve our problems very well. We can let it help us to carry out unit tests and code verification, help us to do github and Gitee synchronization, help us to do document deployment, free our hands, reduce the occurrence of errors.

PR, ISSUE specification

Doing an open source project is sure to receive a lot of PR and issues, but many people do not know what information warehouse owners need most. In order to locate bugs and solve problems more quickly, we can provide pr and issue templates in github warehouse to solve this problem. You can also provide a contribution guide or development manual so that interested people can get involved more quickly.

Write at the end and thank you for your contributions

Varlet wrote his first line of code around October of last year and released version 1.0.0 around May of the following year. The developers are all young people with their own full-time jobs, working in the daytime and working in the evening, all driven by interest. Gradually, some partners in the community joined in, and we got to know a lot of friends. Occasionally, we had small talk and had a dinner with milk tea cloud. Maybe this is the fun of open source, freedom, and everyone can participate in and share. It’s nice to occasionally get validation that you’re doing a good job. Thank you for your contribution. In the future, we will continue to refuel and continue to write code happily. We also hope that all the friends here will be willing to participate in open source and actively share their things.