Evolution of Varlet UI: Architecture, Monorepo, Design System, and Tooling in 2023

Preface

Hello everyone on Juejin, I am the author of the Vue3 mobile component library Varlet UI. Time flies – it is already October 2023, and the last time I shared the library’s architecture was two years ago when Varlet was first open‑sourced and quickly gathered over 4,000 stars with community help.

Two years ago I wrote a post titled “From 0 to 1: Building an Open‑Source Component Library” to record the insights and hopes that others could avoid pitfalls. Since then the front‑end ecosystem has changed dramatically, and Varlet has continuously learned and kept up, making significant progress. In this article I will share, from a library author’s perspective, the recent architectural changes and thinking behind Varlet.

Pnpm Monorepo Split Architecture

Using a monorepo allows us to extract common parts into separate packages for independent publishing and management, reducing dependency maintenance overhead and benefiting the library’s ecosystem. At the project’s start we used yarn workspace + lerna , but after pnpm became popular we switched to pnpm for its better performance, lower disk usage, and superior handling of dependencies, effectively solving ghost‑dependency issues.

The current split structure is as follows:

|-- packages
|-- varlet-cli            # CLI tool managing the library lifecycle
|-- varlet-eslint-config  # ESLint rules for the library
|-- varlet-icons          # Icon packaging tool
|-- varlet-shared         # Shared utilities
|-- varlet-touch-emulator# Desktop adapter
|-- varlet-ui             # Core library
|-- varlet-ui-playground  # Online playground
|-- varlet-use            # Composition API utilities
|-- varlet-vite-plugins   # Vite plugins used by the library
|-- varlet-vscode-extension# VSCode extension for better developer experience

Design System

A design system and design resources are crucial for a component library, acting as a bridge between designers and developers. Without a design system, components lose standards, consistency, and visual quality; without design resources, designers struggle to produce effective design drafts, making it hard for the library to be adopted in products.

Ideally, complete design mockups should be finished before implementing components. Initially we built components first and added design assets later, which caused significant rework and disruptive changes. Tools like Sketch and Figma align well with front‑end developers and are easy to adopt.

Component Writing Style: SFC or TSX

We use a complementary approach of Single‑File Components (SFC) and TSX. SFC is the primary style because Vue’s SFC compiler provides many compile‑time optimizations and better runtime performance. TSX is used to fill gaps where SFC is less convenient, such as VNode manipulation.

Development Environment Embracing Vite

We migrated our development environment from Webpack 5 to Vite and extracted the required Vite plugins into a separate package. Vite serves both as a dev server and a library bundler, making it an ideal choice for a component library documentation site. We also look forward to Rust‑based build tools like Rolldown.

Icon Library

We adopt a traditional font‑icon approach, packaging SVG assets into font files and CSS via varlet-icons for easy consumption by the library.

Vitest Unit Testing

We switched unit testing from Jest to Vitest. Jest’s extensive configuration files were cumbersome, while Vitest shares Vite’s configuration, reducing dependency and configuration maintenance. Vitest also offers significantly faster test execution on modern hardware (e.g., Mac M1), though on single‑core CPUs its speed advantage diminishes; overall, the migration is worthwhile.

Native‑Based JS/TS Compilers

With the rise of native‑based JS/TS compilers, we evaluated several upstream tools. For browser‑side TS libraries we chose tsup (built on esbuild) for its multi‑fold speed advantage over tsc . For Node‑side TS libraries we considered unbuild , but ultimately selected tsup for all non‑component compilation scenarios to keep the toolchain simple.

Our component compilation uses a custom compiler that combines babel and esbuild . Babel handles Vue JSX syntax, while esbuild performs fast compilation and syntax lowering, dramatically accelerating build times.

Build Outputs

To satisfy different usage scenarios we produce three module formats: esm , cjs , and umd . esm is used for modern bundlers, cjs for older Node environments and testing, and umd for CDN usage in browsers. Our custom compiler outputs esm modules with a directory‑structured layout for easy tree‑shaking, and Vite’s library mode generates bundled cjs and umd files.

Documentation Deployment

Following a “no‑cost if possible” principle, we host the Chinese site on Gitee Pages and the international site on Vercel. Deploying both improves access speed for domestic and overseas users. Vercel’s GitHub App integration enables automatic preview deployments for each PR or commit, which is essential for reviewing component visual changes.

Playground

Every component library needs an online editor for feedback, bug reproduction, and issue reporting. We customized Vue’s official playground to build the Varlet Playground; details are in the article “Vue3 Component Online Interactive Interpreter”. Alternatives like CodeSandbox exist but are heavier and slower, especially for users with poor network conditions.

VSCode Extension

Beyond end‑user experience, we aim to improve developer experience. We built a VSCode extension with features such as full component IntelliSense, quick documentation preview, one‑click opening of the playground, full icon preview, and bilingual (English/Chinese) support. The extension and a Varlet theme are available in the VSCode Marketplace.

Conclusion

Thank you for reading. I hope this sharing provides some inspiration. Thanks to the community for supporting Varlet – feel free to open issues, submit PRs, or give a star on the repository.

Repository: https://github.com/varletjs/varlet