shadcn/ui Astro Monorepo 模板實戰用 pnpm Workspaces Turborepo 搭建共享 React 組件庫【免費下載鏈接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.項目地址: https://gitcode.com/GitHub_Trending/ui/ui本篇基于倉庫中的 Astro Monorepo 模板說明文檔完整解析 shadcn/ui 官方提供的 Astro React TypeScript Monorepo 模板apps/web中運行 Astro 應用packages/ui中以 workspace 包形式沉淀共享的 shadcn/ui 組件。讀完后你可以掌握在 pnpm workspace 中配置workspace/ui跨包引用、理解兩份components.json的差異、用 shadcn CLI 向共享包添加組件并在.astro文件中通過client:load正確掛載 React 組件的完整方案。模板定位應用與 UI 包分層模板的核心設計是把“會變化的界面邏輯”和“可復用的 UI 組件”拆開目錄角色說明apps/webAstro 應用頁面、布局依賴workspace/ui消費共享組件packages/ui共享 UI 包workspace/ui存放 shadcn/ui 生成的組件、hooks、工具函數與全局樣式根目錄 templates/astro-monorepo/package.json 聲明了模板的運行基線{ packageManager: pnpm10.33.4, engines: { node: 22.12.0 }, devDependencies: { prettier: ^3.8.3, prettier-plugin-astro: ^0.14.1, prettier-plugin-tailwindcss: ^0.8.0, turbo: ^2.9.18, typescript: ~6 } }即pnpm 10 Node ≥ 22.12 Turborepo 2.9 TypeScript ~6。apps/web/package.json 則給出了具體框架版本astro ^7、astrojs/react ^5、react/react-dom ^19.2.6、tailwindcss/vite ^4Tailwind v4并且以workspace/ui: workspace:*的方式聲明對共享包的工作區依賴。pnpm workspace 與構建腳本白名單pnpm-workspace.yaml 把apps/*與packages/*納入同一工作區packages: - apps/* - packages/* allowBuilds: esbuild: true sharp: true msw: falseallowBuilds字段用于控制依賴的安裝后構建腳本模板放行esbuild、sharp禁用msw避免不需要的依賴在安裝階段執行任意腳本。Turborepo根目錄的統一任務入口turbo.json 定義了根目錄五個腳本build/dev/lint/format/typecheck見根 package.json背后的任務編排{ ui: tui, tasks: { build: { dependsOn: [^build], inputs: [$TURBO_DEFAULT$, .env*], outputs: [dist/**] }, lint: { dependsOn: [^lint] }, format: { dependsOn: [^format] }, typecheck: { dependsOn: [^typecheck] }, dev: { cache: false, persistent: true } } }幾個關鍵點build聲明了dependsOn: [^build]即先構建被依賴的上游包packages/ui再構建消費方apps/web并以dist/**作為緩存產物dev標記為persistent: true且關閉緩存保證pnpm dev能持續運行 Astro 開發服務器而不被 Turborepo 殺掉lint/format/typecheck同樣按依賴拓撲排序兩個包會各自執行本目錄定義的對應腳本例如 apps/web/package.json 的typecheck是astro check而 packages/ui/package.json 的是tsc --noEmit。因此日常只需在倉庫根目錄執行pnpm dev/pnpm build/pnpm typecheck等命令Turborepo 負責分發到各子包。跨包引用的三層配置workspace/ui模板讓apps/web能以“按文件路徑”的方式引用packages/ui中的源碼無需構建產物這一能力由三層配置共同支撐。1. 包級exports子路徑映射packages/ui/package.json 的exports把包內子目錄逐一暴露為子路徑exports: { ./globals.css: ./src/styles/globals.css, ./lib/*: ./src/lib/*.ts, ./components/*: ./src/components/*.tsx, ./hooks/*: ./src/hooks/*.ts }這意味著import { Button } from workspace/ui/components/button會被 Node/Vite 直接解析到packages/ui/src/components/button.tsx源文件——組件是“源碼直連”而非編譯后的dist產物這也是該模板里packages/ui沒有build腳本的原因。2. 應用側 TypeScript 路徑映射apps/web/tsconfig.json 在astro/tsconfigs/strict基礎上補了兩組pathscompilerOptions: { jsx: react-jsx, jsxImportSource: react, paths: { /*: [./src/*], workspace/ui/*: [../../packages/ui/src/*] } }workspace/ui/*映射到packages/ui/src/*后編輯器與類型檢查可以直接跳轉到共享包源碼/*則是 Astro 側的常規src別名。packages/ui/tsconfig.json 內部也做了對稱配置workspace/ui/*: [./src/*]使包內自引用在類型層面一致。3. Tailwind v4 的source掃描范圍Tailwind v4 是 CSS-first 配置無tailwind.config文件樣式入口是 packages/ui/src/styles/globals.cssimport tailwindcss; source ../../../apps/**/*.{ts,tsx,astro}; source ../../../components/**/*.{ts,tsx}; source ../**/*.{ts,tsx};由于組件源碼散落在兩個包、多個目錄里Tailwind 默認的單目錄掃描不足以收集全部候選類名因此這里用source顯式聲明應用側所有.ts/.tsx/.astro文件、包內components與包內全部 TS 源碼都是掃描對象。缺了這幾行跨包組件的類名很可能不會被生成。shadcn 配置兩份components.json的分工模板中apps/web與packages/ui各有一份components.json它們都使用同一套參數語義但指向不同的落盤位置。應用側把生成物路由到共享包apps/web/components.json{ $schema: https://ui.shadcn.com/schema.json, style: radix-nova, rsc: false, tsx: true, tailwind: { config: , css: ../../packages/ui/src/styles/globals.css, baseColor: neutral, cssVariables: true }, iconLibrary: lucide, aliases: { components: /components, hooks: /hooks, lib: /lib, utils: workspace/ui/lib/utils, ui: workspace/ui/components } }逐條看關鍵參數style: radix-nova組件視覺風格rsc: falseAstro 場景不存在 React Server Componentsshadcn 生成代碼時不會添加use client指令——在 Astro 中組件是否水合由client:*指令決定見后文tailwind.css指向跨包路徑../../packages/ui/src/styles/globals.css從apps/web執行 shadcn 命令時CLI 會去修改共享包里的全局樣式而不是應用本地文件保證主題變量單一來源baseColor: neutralcssVariables: true基礎色板為 neutral主題以 CSS 變量形式注入便于運行時換膚iconLibrary: lucide圖標統一來自 lucidealiases中components/hooks/lib仍指向應用自身/...但utils與ui指向workspace/ui——生成的組件依賴cn等工具函數時會引用共享包組件本體則可落在應用內。共享包側以包根為錨點的鏡像配置packages/ui/components.json 與上表的主要差異只有tailwind.css本地相對路徑src/styles/globals.css和aliasesaliases: { components: workspace/ui/components, utils: workspace/ui/lib/utils, hooks: workspace/ui/hooks, lib: workspace/ui/lib, ui: workspace/ui/components }也就是說若直接在packages/ui目錄上下文中運行 shadcn 命令所有產物都會寫入packages/ui內部且包內文件互相引用時也使用workspace/ui/...別名。兩份配置互為鏡像、錨點不同共同保證“無論在哪一層執行 CLI引用解析都收斂到同一套路徑”。添加組件shadcn add 命令按照 README 的說明在倉庫根目錄執行npx shadcnlatest add button -c apps/web-c apps/web將命令上下文定位到apps/webCLI 讀取該目錄的 components.json 完成配置解析組件代碼按其ui別名workspace/ui/components對應的exports映射最終寫入packages/ui/src/components/成為整個工作區共享的組件。從當前倉庫快照看packages/ui/src/components 目錄尚為空hooks、lib亦同而 apps/web/src/pages/index.astro 已預置了對button組件的引用——模板預期的使用順序即先執行上述add命令生成組件文件應用即可直接跑起來。在 Astro 中使用組件README 給出的最小用法是在.astro文件中直接導入并使用組件--- import { Button } from workspace/ui/components/button --- html langen head meta charsetutf-8 / meta nameviewport contentwidthdevice-width / titleAstro App/title /head body div classgrid h-screen place-items-center content-center ButtonButton/Button /div /body /html模板實際首頁 index.astro 在此基礎上展示了一個關鍵的 Astro 集成細節--- import workspace/ui/globals.css import { Button } from workspace/ui/components/button --- body ... Button client:load classNamemt-2Button/Button /body兩點值得注意client:load指令shadcn/ui 組件大量依賴 Radix 原語與客戶端交互折疊、彈出、焦點管理等。在 Astro 中不加client:*的 React 組件只渲染為靜態 HTML加上client:load后 Astro 會在頁面加載時水合該組件交互能力才真正生效。這正是components.json里rsc: false的另一層含義——在 Astro 里客戶端行為的開關在模板指令而不是use client。樣式全局導入一次首頁與 main.astro 布局均通過import workspace/ui/globals.css引入全局樣式它經由 packages/ui/package.json 的./globals.css導出解析到共享包內的 globals.cssTailwind 主題與source掃描規則隨之生效。應用側的 Vite 配置也很簡潔astro.config.mjs 僅掛了兩個插件tailwindcss/viteTailwind v4 的 Vite 集成與astrojs/reactReact 渲染集成import tailwindcss from tailwindcss/vite import { defineConfig } from astro/config import react from astrojs/react export default defineConfig({ vite: { plugins: [tailwindcss()] }, integrations: [react()], })關鍵文件速查文件職責pnpm-workspace.yaml工作區成員與依賴構建腳本白名單turbo.jsonbuild / dev / lint / format / typecheck 任務編排packages/ui/package.jsonworkspace/ui的exports子路徑映射源碼直連packages/ui/components.json包級 shadcn 配置產物落在包內packages/ui/src/styles/globals.cssTailwind v4 入口與source掃描范圍apps/web/components.json應用級 shadcn 配置CSS 指向共享包apps/web/tsconfig.jsonworkspace/ui/*→packages/ui/src/*類型路徑映射apps/web/astro.config.mjsTailwind vite 插件 React 集成apps/web/src/pages/index.astro組件用法示例client:load水合小結這個模板的精髓在于“單一樣式源、單一組件源、多層別名收斂”Tailwind 主題只存在于packages/ui/src/styles/globals.cssshadcn 生成的組件通過exportspathssource三層配置被應用無縫引用Turborepo 則把多包項目的日常命令壓縮為根目錄一條指令。理解了 apps/web/components.json 與 packages/ui/components.json 的分工以及client:load在 Astro 中的水合作用就可以在此基礎上持續向packages/ui添加組件并擴展到多個前端應用。【免費下載鏈接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.項目地址: https://gitcode.com/GitHub_Trending/ui/ui創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 shadcn/ui Astro Monorepo 模板實戰：用 pnpm Workspaces + Turborepo 搭建共享 React 組件庫
shadcn/ui Astro Monorepo 模板實戰用 pnpm Workspaces Turborepo 搭建共享 React 組件庫【免費下載鏈接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.項目地址: https://gitcode.com/GitHub_Trending/ui/ui本篇基于倉庫中的 Astro Monorepo 模板說明文檔完整解析 shadcn/ui 官方提供的 Astro React TypeScript Monorepo 模板apps/web中運行 Astro 應用packages/ui中以 workspace 包形式沉淀共享的 shadcn/ui 組件。讀完后你可以掌握在 pnpm workspace 中配置workspace/ui跨包引用、理解兩份components.json的差異、用 shadcn CLI 向共享包添加組件并在.astro文件中通過client:load正確掛載 React 組件的完整方案。模板定位應用與 UI 包分層模板的核心設計是把“會變化的界面邏輯”和“可復用的 UI 組件”拆開目錄角色說明apps/webAstro 應用頁面、布局依賴workspace/ui消費共享組件packages/ui共享 UI 包workspace/ui存放 shadcn/ui 生成的組件、hooks、工具函數與全局樣式根目錄 templates/astro-monorepo/package.json 聲明了模板的運行基線{ packageManager: pnpm10.33.4, engines: { node: 22.12.0 }, devDependencies: { prettier: ^3.8.3, prettier-plugin-astro: ^0.14.1, prettier-plugin-tailwindcss: ^0.8.0, turbo: ^2.9.18, typescript: ~6 } }即pnpm 10 Node ≥ 22.12 Turborepo 2.9 TypeScript ~6。apps/web/package.json 則給出了具體框架版本astro ^7、astrojs/react ^5、react/react-dom ^19.2.6、tailwindcss/vite ^4Tailwind v4并且以workspace/ui: workspace:*的方式聲明對共享包的工作區依賴。pnpm workspace 與構建腳本白名單pnpm-workspace.yaml 把apps/*與packages/*納入同一工作區packages: - apps/* - packages/* allowBuilds: esbuild: true sharp: true msw: falseallowBuilds字段用于控制依賴的安裝后構建腳本模板放行esbuild、sharp禁用msw避免不需要的依賴在安裝階段執行任意腳本。Turborepo根目錄的統一任務入口turbo.json 定義了根目錄五個腳本build/dev/lint/format/typecheck見根 package.json背后的任務編排{ ui: tui, tasks: { build: { dependsOn: [^build], inputs: [$TURBO_DEFAULT$, .env*], outputs: [dist/**] }, lint: { dependsOn: [^lint] }, format: { dependsOn: [^format] }, typecheck: { dependsOn: [^typecheck] }, dev: { cache: false, persistent: true } } }幾個關鍵點build聲明了dependsOn: [^build]即先構建被依賴的上游包packages/ui再構建消費方apps/web并以dist/**作為緩存產物dev標記為persistent: true且關閉緩存保證pnpm dev能持續運行 Astro 開發服務器而不被 Turborepo 殺掉lint/format/typecheck同樣按依賴拓撲排序兩個包會各自執行本目錄定義的對應腳本例如 apps/web/package.json 的typecheck是astro check而 packages/ui/package.json 的是tsc --noEmit。因此日常只需在倉庫根目錄執行pnpm dev/pnpm build/pnpm typecheck等命令Turborepo 負責分發到各子包。跨包引用的三層配置workspace/ui模板讓apps/web能以“按文件路徑”的方式引用packages/ui中的源碼無需構建產物這一能力由三層配置共同支撐。1. 包級exports子路徑映射packages/ui/package.json 的exports把包內子目錄逐一暴露為子路徑exports: { ./globals.css: ./src/styles/globals.css, ./lib/*: ./src/lib/*.ts, ./components/*: ./src/components/*.tsx, ./hooks/*: ./src/hooks/*.ts }這意味著import { Button } from workspace/ui/components/button會被 Node/Vite 直接解析到packages/ui/src/components/button.tsx源文件——組件是“源碼直連”而非編譯后的dist產物這也是該模板里packages/ui沒有build腳本的原因。2. 應用側 TypeScript 路徑映射apps/web/tsconfig.json 在astro/tsconfigs/strict基礎上補了兩組pathscompilerOptions: { jsx: react-jsx, jsxImportSource: react, paths: { /*: [./src/*], workspace/ui/*: [../../packages/ui/src/*] } }workspace/ui/*映射到packages/ui/src/*后編輯器與類型檢查可以直接跳轉到共享包源碼/*則是 Astro 側的常規src別名。packages/ui/tsconfig.json 內部也做了對稱配置workspace/ui/*: [./src/*]使包內自引用在類型層面一致。3. Tailwind v4 的source掃描范圍Tailwind v4 是 CSS-first 配置無tailwind.config文件樣式入口是 packages/ui/src/styles/globals.cssimport tailwindcss; source ../../../apps/**/*.{ts,tsx,astro}; source ../../../components/**/*.{ts,tsx}; source ../**/*.{ts,tsx};由于組件源碼散落在兩個包、多個目錄里Tailwind 默認的單目錄掃描不足以收集全部候選類名因此這里用source顯式聲明應用側所有.ts/.tsx/.astro文件、包內components與包內全部 TS 源碼都是掃描對象。缺了這幾行跨包組件的類名很可能不會被生成。shadcn 配置兩份components.json的分工模板中apps/web與packages/ui各有一份components.json它們都使用同一套參數語義但指向不同的落盤位置。應用側把生成物路由到共享包apps/web/components.json{ $schema: https://ui.shadcn.com/schema.json, style: radix-nova, rsc: false, tsx: true, tailwind: { config: , css: ../../packages/ui/src/styles/globals.css, baseColor: neutral, cssVariables: true }, iconLibrary: lucide, aliases: { components: /components, hooks: /hooks, lib: /lib, utils: workspace/ui/lib/utils, ui: workspace/ui/components } }逐條看關鍵參數style: radix-nova組件視覺風格rsc: falseAstro 場景不存在 React Server Componentsshadcn 生成代碼時不會添加use client指令——在 Astro 中組件是否水合由client:*指令決定見后文tailwind.css指向跨包路徑../../packages/ui/src/styles/globals.css從apps/web執行 shadcn 命令時CLI 會去修改共享包里的全局樣式而不是應用本地文件保證主題變量單一來源baseColor: neutralcssVariables: true基礎色板為 neutral主題以 CSS 變量形式注入便于運行時換膚iconLibrary: lucide圖標統一來自 lucidealiases中components/hooks/lib仍指向應用自身/...但utils與ui指向workspace/ui——生成的組件依賴cn等工具函數時會引用共享包組件本體則可落在應用內。共享包側以包根為錨點的鏡像配置packages/ui/components.json 與上表的主要差異只有tailwind.css本地相對路徑src/styles/globals.css和aliasesaliases: { components: workspace/ui/components, utils: workspace/ui/lib/utils, hooks: workspace/ui/hooks, lib: workspace/ui/lib, ui: workspace/ui/components }也就是說若直接在packages/ui目錄上下文中運行 shadcn 命令所有產物都會寫入packages/ui內部且包內文件互相引用時也使用workspace/ui/...別名。兩份配置互為鏡像、錨點不同共同保證“無論在哪一層執行 CLI引用解析都收斂到同一套路徑”。添加組件shadcn add 命令按照 README 的說明在倉庫根目錄執行npx shadcnlatest add button -c apps/web-c apps/web將命令上下文定位到apps/webCLI 讀取該目錄的 components.json 完成配置解析組件代碼按其ui別名workspace/ui/components對應的exports映射最終寫入packages/ui/src/components/成為整個工作區共享的組件。從當前倉庫快照看packages/ui/src/components 目錄尚為空hooks、lib亦同而 apps/web/src/pages/index.astro 已預置了對button組件的引用——模板預期的使用順序即先執行上述add命令生成組件文件應用即可直接跑起來。在 Astro 中使用組件README 給出的最小用法是在.astro文件中直接導入并使用組件--- import { Button } from workspace/ui/components/button --- html langen head meta charsetutf-8 / meta nameviewport contentwidthdevice-width / titleAstro App/title /head body div classgrid h-screen place-items-center content-center ButtonButton/Button /div /body /html模板實際首頁 index.astro 在此基礎上展示了一個關鍵的 Astro 集成細節--- import workspace/ui/globals.css import { Button } from workspace/ui/components/button --- body ... Button client:load classNamemt-2Button/Button /body兩點值得注意client:load指令shadcn/ui 組件大量依賴 Radix 原語與客戶端交互折疊、彈出、焦點管理等。在 Astro 中不加client:*的 React 組件只渲染為靜態 HTML加上client:load后 Astro 會在頁面加載時水合該組件交互能力才真正生效。這正是components.json里rsc: false的另一層含義——在 Astro 里客戶端行為的開關在模板指令而不是use client。樣式全局導入一次首頁與 main.astro 布局均通過import workspace/ui/globals.css引入全局樣式它經由 packages/ui/package.json 的./globals.css導出解析到共享包內的 globals.cssTailwind 主題與source掃描規則隨之生效。應用側的 Vite 配置也很簡潔astro.config.mjs 僅掛了兩個插件tailwindcss/viteTailwind v4 的 Vite 集成與astrojs/reactReact 渲染集成import tailwindcss from tailwindcss/vite import { defineConfig } from astro/config import react from astrojs/react export default defineConfig({ vite: { plugins: [tailwindcss()] }, integrations: [react()], })關鍵文件速查文件職責pnpm-workspace.yaml工作區成員與依賴構建腳本白名單turbo.jsonbuild / dev / lint / format / typecheck 任務編排packages/ui/package.jsonworkspace/ui的exports子路徑映射源碼直連packages/ui/components.json包級 shadcn 配置產物落在包內packages/ui/src/styles/globals.cssTailwind v4 入口與source掃描范圍apps/web/components.json應用級 shadcn 配置CSS 指向共享包apps/web/tsconfig.jsonworkspace/ui/*→packages/ui/src/*類型路徑映射apps/web/astro.config.mjsTailwind vite 插件 React 集成apps/web/src/pages/index.astro組件用法示例client:load水合小結這個模板的精髓在于“單一樣式源、單一組件源、多層別名收斂”Tailwind 主題只存在于packages/ui/src/styles/globals.cssshadcn 生成的組件通過exportspathssource三層配置被應用無縫引用Turborepo 則把多包項目的日常命令壓縮為根目錄一條指令。理解了 apps/web/components.json 與 packages/ui/components.json 的分工以及client:load在 Astro 中的水合作用就可以在此基礎上持續向packages/ui添加組件并擴展到多個前端應用。【免費下載鏈接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.項目地址: https://gitcode.com/GitHub_Trending/ui/ui創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考