@yugen-ui/cli

Không cần cài trước: chạy bằng npx @yugen-ui/cli@latest (hoặc pnpm dlx, yarn dlx, bunx). Cần Node.js 24 trở lên.

npx @yugen-ui/cli@latest create my-app

Tuỳ chọn: -t, --template, --lang en|vi (ngôn ngữ chữ trong app, với template có cả hai; mặc định tiếng Anh), --pm npm|pnpm|yarn|bun, --no-install, --no-git, --force (ghi vào thư mục không trống). npx create-yugen-ui@latest là cách gọi ngắn của lệnh này. Template nằm sẵn trong gói nên không cần mạng. Xem trước ở Templates.

npx @yugen-ui/cli@latest init

npx @yugen-ui/cli@latest init --mode source

Kết quả ở chế độ source với dự án Vite có alias @/:

yugen.json
src/
  index.css                           # thêm @import "./yugen.css"; sau @import "tailwindcss";
  yugen.css                           # theme
  lib/cn.ts
  lib/cvx.ts                          # cùng yugen add button (class theo biến thể)
  components/ui/YugenProvider/…       # cùng Toast, Tooltip mà provider dùng
  components/ui/Button/Button.tsx     # từ yugen add

Import trong mã chép vào dùng alias của tsconfig (@/*, ~/*) nếu có, không thì dùng đường dẫn tương đối, nên không phải sửa vite.config. Dòng "use client" chỉ được giữ với Next.js. Cuối cùng CLI hỏi để bọc app trong <YugenProvider applyToDocument> với <Toaster /> và <App /> trong main.tsx (Vite) hoặc {children} trong <body> của app/layout.tsx (Next.js). Cấu trúc khác, hoặc chạy với --no-provider, thì CLI in đoạn cần thêm kèm tên file.

npx @yugen-ui/cli@latest add button dialog data-grid

npx @yugen-ui/cli add select --dry-run    # in danh sách file sẽ ghi, không ghi gì
npx @yugen-ui/cli add --all               # mọi component
npx @yugen-ui/cli add button --overwrite  # ghi đè cả file bạn đã sửa
npx @yugen-ui/cli list grid               # tìm trong registry, ✓ là đã có trong dự án

File đã có và khác registry (thường là bạn đã sửa) được giữ nguyên, CLI liệt kê chúng. Xem khác ở đâu bằng yugen diff, nhận bản mới bằng yugen update (phần bên dưới).

npx @yugen-ui/cli diff                   # mọi component đã chép: in diff so với registry
npx @yugen-ui/cli update button --dry-run # xem diff, không ghi
npx @yugen-ui/cli update                  # áp bản registry (hỏi lại trước khi ghi)
npx @yugen-ui/cli remove data-grid        # xoá file không còn được import ở đâu

update in diff của từng file sẽ đổi, báo file mới (ví dụ phụ thuộc vừa thêm vào registry) rồi hỏi lại trước khi ghi; phần bạn đã sửa trong các file đó bị thay. Commit trước để giữ được phần tuỳ biến. remove quét import trong dự án (đường dẫn tương đối và alias) và giữ lại file còn được dùng, ví dụ Spinner khi Button vẫn import nó. Gói npm không bị gỡ.

npx @yugen-ui/cli css                       # ghi src/yugen-ui.css, import trong src/index.css
npx @yugen-ui/cli css --check               # CI: thoát với mã 1 khi file đã cũ, không ghi gì
npx @yugen-ui/cli css --src app --src lib   # chỉ đọc các thư mục này (mặc định: cả dự án)
npx @yugen-ui/cli css --precompile          # app không dùng Tailwind: CSS đã biên dịch, thay styles.css
npx @yugen-ui/cli css --watch               # tự ghi lại khi import component thay đổi

// vite.config.ts
import { yugenCss } from "@yugen-ui/cli/vite";
plugins: [yugenCss()]

/* src/yugen-ui.css */
@import "yugen-ui/theme-core.css";
@import "yugen-ui/sources/Button.css";
@import "yugen-ui/sources/Dialog.css";
@import "yugen-ui/sources/YugenProvider.css";

Lệnh đọc import từ yugen-ui trong mã của app, cả đường dẫn con như yugen-ui/Dialog. Import kiểu và ví dụ viết trong chuỗi hay chú thích không được tính. Mỗi tên được tra thư mục trong yugen-ui/sources/index.json, mỗi thư mục là một dòng. Lần chạy đầu thay @import "yugen-ui/theme.css" trong file CSS chính bằng @import "./yugen-ui.css". Với các template, CSS gzip giảm từ khoảng 26 kB xuống 12–20 kB (bảng ở Tuỳ biến style).

Import thêm component thì chạy lại lệnh; ở chế độ package yugen add <tên> tự làm. Muốn luôn khớp thì cài CLI làm dev dependency và thêm "predev": "yugen css", "prebuild": "yugen css" vào package.json. Đầu file ghi lệnh đã tạo ra nó (kể cả --src, --out), nên lần sau chỉ cần yugen css.

import * as Yugen from "yugen-ui", export * from "yugen-ui" hay import("yugen-ui") có thể dùng mọi component, nên file quay về theme.css và ghi rõ file nào gây ra. Component được import trong một gói khác của monorepo thì lệnh không thấy: thêm thư mục đó bằng --src.

--precompile dành cho app không dùng Tailwind: cùng danh sách đó được biên dịch thành CSS thường bằng tailwindcss, @tailwindcss/node và @tailwindcss/oxide của chính dự án (cài làm dev dependency, CLI không mang theo Tailwind), rồi thay import "yugen-ui/styles.css" trong file gốc. Với các template: 26.8 kB còn 12.8–21.1 kB gzip.

npx @yugen-ui/cli theme --brand #0f6cbd --name acme
# → src/yugen-brand.css: [data-brand="acme"] { --brand-10 … --brand-160 }, import trong src/index.css
# <YugenProvider applyToDocument brand="acme"><Toaster />…</YugenProvider>

Tuỳ chọn --vibrancy (50–150) và --torsion (−30…30) như hai thanh trượt của Theme Designer. Chữ trắng trên nút primary dưới 4.5:1 thì CLI cảnh báo và gợi ý một màu key tối hơn đạt chuẩn. Muốn chỉnh thêm bo góc, mật độ, font… thì dùng Theme Designer.

npx @yugen-ui/cli@latest doctor

◆  yugen.json: source mode
◆  React 19.3.1
◆  Tailwind CSS 4.3.3
◆  Theme imported: src/index.css → ./yugen.css
◆  15 component folders in src/components/ui
▲  YugenProvider not found
│  Wrap your app once: <YugenProvider applyToDocument><Toaster />…</YugenProvider>
└  Looks good, 1 warning

Các mục kiểm tra: React 19 trở lên, Tailwind CSS v4 khi dùng theme, theme được import đúng một lần và đứng sau @import "tailwindcss", yugen-ui.css đã được import và còn khớp với mã (cảnh báo khi đã cũ), component được import mà thiếu file sources khi bạn tự viết các dòng theme-core.css, bản yugen-ui đã cài so với bản mới nhất trên npm, thư mục component và cn.ts ở chế độ source, có dùng YugenProvider.

init ghi file này ở gốc dự án; add, list và doctor đọc nó. Có thể sửa tay, ví dụ đổi paths.ui để đặt component ở thư mục khác. Không có file này mà dự án đã cài yugen-ui (vd. app tạo bằng create) thì CLI coi là mode package.

{
  "mode": "source",
  "framework": "vite",
  "rsc": false,
  "css": "src/index.css",
  "paths": { "ui": "src/components/ui", "lib": "src/lib" },
  "aliases": { "ui": "@/components/ui", "lib": "@/lib" }
}

Component lấy từ registry https://trandat1114.github.io/Yugen-UI/r, cùng nguồn với shadcn CLI. Dự án đã chạy shadcn init với registry Yugen dùng được yugen add ngay vì CLI đọc components.json. Dùng registry khác hoặc thư mục local (public/r sau npm run registry khi phát triển Yugen) bằng --registry hoặc trường registry trong yugen.json.