Building a Custom Vue Component Library with Vant CLI: A Step‑by‑Step Guide

Component design involves breaking down functional and visual elements into reusable, standardized components that can be combined to form a complete design system; assembling these components creates a component library. This guide focuses on building a custom Vue component library using Vant CLI, a Vite‑based tool for quickly scaffolding full‑featured Vue component libraries.

Why build a component library? It reduces cost and improves efficiency, ensures visual and interaction consistency, speeds up scenario construction, and simplifies iterative upgrades across multiple projects by updating a single codebase.

How to create the library

1. Catalog components : Identify modules with similar styles, discuss future plans, and decide whether existing components meet needs; create independent tasks for each component.

2. Integrate scenarios : Experience the product as an end user, map user flows, and gather all current and potential usage scenarios to avoid omissions.

3. Select a library framework : Review popular Vue 3 UI libraries (e.g., element‑plus, tdesign‑vue‑next, arco‑design‑vue, ant‑design‑vue, naive‑ui, vant, nutui, vuetify, varlet) and choose Vant for this guide.

4. Set up Vant CLI

Ensure Node version ^12.13.0, ^14.15.0, or >=16.0.0, then run:

yarn create vant-cli-app

Install the CLI:

# via npm
npm i @vant/cli -D
# via yarn
yarn add @vant/cli -D
# via pnpm
pnpm add @vant/cli -D

Configure package.json scripts:

{
  "scripts": {
    "dev": "vant-cli dev",
    "test": "vant-cli test",
    "lint": "vant-cli lint",
    "build": "vant-cli build",
    "prepare": "husky install",
    "release": "vant-cli release",
    "build-site": "vant-cli build-site"
  },
  "nano-staged": {
    "*.md": "prettier --write",
    "*.{ts,tsx,js,vue,less,scss}": "prettier --write",
    "*.{ts,tsx,js,vue}": "eslint --fix"
  },
  "eslintConfig": { "root": true, "extends": ["@vant"] },
  "prettier": { "singleQuote": true },
  "browserslist": ["Chrome >= 51", "iOS >= 10"]
}

Start the development server with npm run dev and view the running page.

Development workflow

Directory layout:

m-tetris
├─ build   # build scripts
├─ docs    # documentation site
├─ es      # ES module output
├─ lib     # CommonJS output
├─ site    # static site assets
├─ src     # component source (one folder per component)
├─ test    # unit tests
└─ static  # images and other assets

When adding a new component, follow this structure and register the component name in vant.config.js :

src
└─ button
   ├─ demo      # example code
   ├─ test      # unit tests
   ├─ index.vue # component entry
   ├─ index.less# component styles
   └─ README.md # documentation

Build and package the library:

# Build lib and es folders
npm run build

# Create a tarball
npm pack

# Install the tarball in another project
npm install /absolute/path/to/package.tgz

Publishing

Publish to a private npm registry or the public npm registry (refer to npm’s official npm publish documentation):

# Pull latest master
# Build the npm package
npm run build

# Login if needed
npm login

# Publish (ensure the registry is set appropriately)
npm publish

Using the library in a project

Method 1 – Automatic on‑demand import (recommended) via babel-plugin-import :

# Install plugin
npm i babel-plugin-import -D

// .babelrc configuration
{
  "plugins": [
    ["import", {
      "libraryName": "xxx-vant",
      "libraryDirectory": "es",
      "style": true
    }]
  ]
}

// Then import components directly
import { IndexBar } from 'xxx-vant';

Method 2 – Manual on‑demand import:

import Button from 'xxx-vant/lib/index-bar';
import 'xxx-vant/lib/index-bar/style';

Method 3 – Import all components (not recommended due to bundle size):

import Vue from 'vue';
import XxVant from 'xxx-vant';
import 'xxx-vant/lib/index.css';
Vue.use(XxVant);

Reference: Vant‑CLI documentation – https://github.com/youzan/vant/blob/HEAD/packages/vant-cli/README.zh-CN.md