安裝

先決條件

Node.js 22 以上。shadcn-vue 2.8.2 需 Node ≥ 22；Node 20 執行 CLI 會出現 undici 錯誤。

專案需已完成 shadcn-vue 設定，且 components.json 的 iconLibrary 為 tabler：

• Vite
• Nuxt

@admin 元件直接 import @tabler/icons-vue。shadcn-vue CLI 會依 iconLibrary，把 registry dependencies 裡已知的 icon 套件換成該設定對應的套件。未指定時預設是 lucide，此時不會改寫這些 import，因此 add @admin/dialog 等元件後 build 會找不到 @tabler/icons-vue。

尚未初始化時：

pnpm dlx shadcn-vue init --icon-library tabler

完成後確認 components.json 含：

{  "iconLibrary": "tabler"}

已是 lucide 或已有 components.json

把 iconLibrary 改成 "tabler"，再執行 pnpm dlx shadcn-vue add。CLI 才會安裝 @tabler/icons-vue。

元件已經寫入、build 仍找不到套件時：

pnpm add @tabler/icons-vue

設定 Registry

在根目錄 components.json 加入 @admin，並保留 iconLibrary：

{  "iconLibrary": "tabler",  "registries": {    "@admin": {      "url": "https://component-registry-4d4d86.gitlab.io/r/styles/admin/{name}.json"    }  }}

Registry 授權

目前 @admin 網址免授權即可讀取。若之後改為需授權，在 @admin 加 headers，並在環境變數設定 REGISTRY_TOKEN：

{  "registries": {    "@admin": {      "url": "https://component-registry-4d4d86.gitlab.io/r/styles/admin/{name}.json",      "headers": {        "Authorization": "Bearer ${REGISTRY_TOKEN}"      }    }  }}

安裝設計系統樣式

pnpm dlx shadcn-vue add @admin/style

驗證：專案應能解析 admin color tokens 與 typo-*；細節見 主題。

Agent skill（可選）

要以 AI agent 依 Setup／Install／Compose 操作 @admin 時，見 Agent skill。

安裝元件

pnpm dlx shadcn-vue add @admin/button

一次多個：

pnpm dlx shadcn-vue add @admin/button @admin/input @admin/dialog

驗證：對應元件出現在 components.json 設定的 components 目錄（常見為 @/components/admin/）。

SSR（Nuxt）

元件本身不包 <ClientOnly>，純 Vue 3 專案可直接用。

不支援 SSR 的元件（依賴 DOM、canvas、WASM）在 Nuxt 自行包：

<template>  <client-only>    <admin-vxe-table :columns="columns" :data="data" />    <template #fallback>      <!-- 可選：骨架或 loading -->    </template>  </client-only></template>

元件同名警告 NUXT_B3011

安裝 @admin/button、@admin/dialog 等元件後，Nuxt build 可能出現：

[NUXT_B3011] Two component files resolving to the same name AdminButton

原因：Nuxt 預設會把 .ts 也當成元件掃描，元件資料夾裡的 index.ts（barrel 匯出檔）會被解析成與 admin-button.vue 同名的元件。這只是警告，不影響 build 與執行。在 nuxt.config.ts 設定只掃描 .vue 檔即可避開：

export default defineNuxtConfig({  components: {    dirs: [{ path: '~/components', extensions: ['.vue'] }]  }})

已使用 shadcn-nuxt 的專案，也可以把兩個目錄都列進 componentDir（兩個都要列，只列 @/components/admin 會讓 ui 目錄出現同樣的警告）：

export default defineNuxtConfig({  shadcn: {    prefix: '',    componentDir: ['@/components/ui', '@/components/admin']  }})