# 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](./README.zh-CN.md) | [组件库中文介绍](./docs/INTRODUCTION.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 `` and ``. ## 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 ```bash npm install @czxingyu/xycomponents pnpm add @czxingyu/xycomponents yarn add @czxingyu/xycomponents ``` ```ts import XyComponents from "@czxingyu/xycomponents"; import "@czxingyu/xycomponents/style"; app.use(XyComponents); ``` ### Install this repository ```bash pnpm install ``` ### Run the docs app ```bash pnpm run docs:dev ``` The local docs site runs on [http://localhost:6878](http://localhost:6878). ### Build the library ```bash pnpm run build ``` ### Other useful commands ```bash 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. ```bash 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@` when upgrading; the CLI updates with the package. Cursor Agent Skills live in [`skills/`](./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`](./skills/README.md). The CLI catalog covers every documented component with detailed props, events, slots, examples, and AI hints. Use `pnpm exec xycomponents migrate --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: ```ts /// ``` 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 ```text . ├─ 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: ```bash 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/`](./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: ```md Basic example ``` 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: ```ts 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`](./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 `` 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`](./components/style/vars.css); extend tokens there instead of hardcoding component values. ## Maintenance workflow 1. Read [`library-readiness.md`](./docs/maintenance/library-readiness.md) before expanding the baseline. 2. Follow [`component-development.md`](./docs/maintenance/component-development.md) for additions and [`ai-bugfix.md`](./docs/maintenance/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`](./README.zh-CN.md).