@czxingyu/xycomponents

xycomponents

A Vue 3 component library project for building first-party xy-* components.

xycomponents combines component-library packaging, a live documentation site, and a Markdown demo pipeline in one codebase, so components and documentation can evolve together.

Chinese docs: README.zh-CN.md | 组件库中文介绍

Before you start

The npm package name is @czxingyu/xycomponents; the library brand remains xycomponents.

Public Vue component names use the Xy prefix, and template tags use the xy- prefix, such as <xy-button> and <xy-input>.

Theme customization

This project is intentionally theme-neutral.

It does not lock you into a built-in business theme. You are expected to define your own brand style, design tokens, color system, component appearance, and other theme effects according to your product requirements.

Why this project

Use this repository when you want to:

• build a first-party Vue component library with the xy- prefix
• keep source code, demos, and documentation in one place
• ship typed Vue 3 components with ESM and UMD outputs
• write docs in Markdown while rendering real Vue demos inline
• maintain Chinese and English documentation pages in the same structure
• build your own theme system instead of inheriting a fixed visual style

What is included

• Vue 3 + TypeScript + Vite
• first-party base components for the documentation site
• library builds for module output, bundled ESM, and UMD
• generated type declarations for components
• custom Markdown-to-Vue pipeline for the docs app
• live demo blocks with source extraction and hot updates
• UnoCSS, Vue Router, Pinia, and Vue I18n integration
• no built-in business theme, making custom theming easier
• sample components and docs pages you can extend directly

Quick start

Requirements

• Node.js ^20.19.0 || >=22.12.0
• pnpm 10.32.1

Install in an app

npm install @czxingyu/xycomponents
pnpm add @czxingyu/xycomponents
yarn add @czxingyu/xycomponents

import XyComponents from "@czxingyu/xycomponents";
import "@czxingyu/xycomponents/style";

app.use(XyComponents);

Install this repository

pnpm install

Run the docs app

pnpm run docs:dev

The local docs site runs on http://localhost:6878.

Build the library

pnpm run build

Other useful commands

pnpm run check
pnpm test
pnpm run test:e2e
pnpm run audit:components
pnpm run ci
pnpm run check:esm-import
pnpm run check:packed-consumer
pnpm run docs:build
pnpm run docs:preview
pnpm run type-check

CLI and Skills for AI-assisted usage

The xycomponents CLI ships inside @czxingyu/xycomponents and always matches the installed package version. Install the library in your app and invoke the CLI locally—do not install the CLI globally.

pnpm add @czxingyu/xycomponents
pnpm exec xycomponents doctor --json
pnpm exec xycomponents components --json
pnpm exec xycomponents component button --json
pnpm exec xycomponents snippet button --example primary
pnpm exec xycomponents migrate link --json
pnpm exec xycomponents package --json

Re-run pnpm add @czxingyu/xycomponents@<version> when upgrading; the CLI updates with the package.

Cursor Agent Skills live in skills/ (xycomponents-shared, xycomponents-cli). Copy them into a consumer project's .cursor/skills/ or from node_modules/@czxingyu/xycomponents/skills/ after install. See skills/README.md.

The CLI catalog covers every documented component with detailed props, events, slots, examples, and AI hints. Use pnpm exec xycomponents migrate <name> --json before replacing deprecated APIs. The release gate installs the packed tarball into an isolated consumer and executes the project-local CLI before publishing.

Global component types

Applications that install the default plugin can opt into template types for all globally registered components from an environment declaration file:

/// <reference types="@czxingyu/xycomponents/global" />

Keep this opt-in out of projects that only use on-demand imports. The release gate verifies that all 89 components registered by the default plugin match the published GlobalComponents declarations exactly.

Project structure

.
├─ cli/                        # AI-readable component metadata and CLI entry
├─ components/                 # Your business components
│  ├─ button/
│  └─ form/
├─ docs/                       # Documentation app
│  ├─ src/pages/               # Markdown pages and Vue home page
│  ├─ src/components/demo/     # Demo renderer and source viewer
│  └─ plugins/markdown/        # Markdown and demo transformation pipeline
├─ vite.build.config.ts        # Preserve-module component build
├─ vite.cli.config.ts          # CLI binary build
├─ vite.esm.config.ts          # Bundled ESM build
├─ vite.umd.config.ts          # UMD build
└─ global.d.ts                 # Global component typings

Development workflow

1. Add components

Start with the generator so source, tests, docs, global types, exports, and detailed AI CLI metadata stay aligned:

pnpm generate:component -- UserCard --title 用户卡片 --group data-display --description 展示用户资料。

Then replace the generated placeholder behavior, types, tests, docs, demo, and AI metadata with the real API. Every unfinished artifact carries an @xy-component-placeholder marker, so pnpm run audit:components intentionally fails with an actionable file list until all generated placeholders have been implemented. Remove each marker only after replacing that artifact; do not bulk-delete the markers.

2. Write documentation pages

Add Markdown pages under docs/src/pages/. This project auto-registers .md pages as routes through import.meta.glob.

Recommended locale naming:

• *.zh-CN.md
• *.en-US.md

The current router uses zh-CN as the default locale and appends a suffix for non-default locale routes.

3. Add demos next to docs pages

Place demo files in a sibling demo/ directory, then reference them with:

<demo-group>
  <demo src="./demo/basic.vue">Basic example</demo>
</demo-group>

The docs pipeline will:

• render the live Vue demo
• extract component source
• generate highlighted code blocks
• hot-update demo metadata during development

Build output

Running pnpm run build produces five kinds of outputs:

• preserved module files in dist/
• bundled ESM entry as dist/index.esm.js
• Empty and Result images as relative dist/assets/* files for the bundled ESM entry
• curated lightweight ESM entry as dist/index.lite.esm.js
• bundled UMD entry as dist/index.umd.js

This makes the library suitable both for modular consumption and for traditional bundled distribution.

The optional lite plugin excludes the asset-heavy Empty, List, Result, Table, and Transfer families. It keeps common internal icons and lets applications register additional icon loaders before mount:

import XyComponentsLite, { setXyIconLoader } from "@czxingyu/xycomponents/lite";
import "@czxingyu/xycomponents/lite/style";

setXyIconLoader(
  "environment-outlined",
  () => import("@ant-design/icons-vue/EnvironmentOutlined"),
);
app.use(XyComponentsLite);

See docs/maintenance/lite-entry.md for the stable exclusions and maintenance rules.

Tech notes

• The docs app treats Markdown files as Vue components.
• Demo parsing supports custom <docs> blocks inside demo SFCs.
• Component usage inside the docs app is wired through the local package entry, so the docs site always reflects the current workspace code.
• Theme, typography, control sizing, and component variables are centralized in components/style/vars.css; extend tokens there instead of hardcoding component values.

Maintenance workflow

1. Read library-readiness.md before expanding the baseline.
2. Follow component-development.md for additions and ai-bugfix.md for fixes.
3. Run pnpm run ci; it keeps runtime exports, global typings, docs APIs, browser flows, package formats, and the packed consumer aligned.

Chinese README

Chinese documentation is available in README.zh-CN.md.