建立新專案
本指南說明如何從 app-office 或 app-office-mockup 參考實作建立新的 React 專案。
選擇起點
AppFuse 提供兩個前端參考實作：
| 專案 | 使用時機 | API |
|---|---|---|
| app-office-mockup | Prototype 開發、需求確認 | Mock API (MSW) |
| app-office | 生產環境開發 | 支援 Mock → 真實 API 漸進切換 |
建議：從 app-office 開始，因為它支援 Mock API 與真實 API 的彈性切換。
:::warning 複製後仍須確認框架版本
參考實作與框架各自發布，兩者不保證在同一個 commit 已使用相同的最新版號。複製後請比對
package.json 與當前發布線，並按
框架升級指南完成升級與驗證。
:::
方式一：從 app-office 複製（推薦）
1. 複製專案
# 取得 monorepo，再只複製目標模組
git clone https://gitlab.com/appfuse/webapp/appfuse-webapps-v1.git
cp -R appfuse-webapps-v1/modules/app-office my-web-app
cd my-web-app
# 建立新專案自己的 Git 歷史
git init
2. 更新專案資訊
編輯 package.json，修改專案資訊：
{
"name": "my-web-app",
"version": "0.0.1",
"description": "My Web Application",
"author": "Your Name <your.email@example.com>"
}
3. 安裝依賴
npm install
4. 清理示範資料
app-office 包含花店管理系統的示範資料，建議保留結構但清空業務邏輯：
# 移除示範 Applets
rm -rf src/applets/product-applet
rm -rf src/applets/order-applet
# 同步移除 src/config/applet-registry.ts 中對應註冊項與 routes
# 移除示範 Mock Handlers
rm src/mocks/handlers/products.ts
rm src/mocks/handlers/orders.ts
# 保留 auth、tenant 等基礎 handlers；商品與訂單 seed 集中在 data/seeds.ts
刪除檔案後，還要同步清除 handlers/index.ts、data/db.ts、data/seeds.ts、
applet registry 與 route 中的 import／註冊項，再執行 npm run build；只刪目錄會留下
編譯錯誤。
5. 更新應用程式配置
編輯 src/conf/config.ts：
export const config: AppEnvironConfig = {
app: {
name: 'My Web App',
version: '0.0.1',
basename: '/',
baseURL: '/',
// 保留既有 msw、auth 等設定
},
// 保留既有 i18n 設定
};
並在 .env 設定開發模式：
VITE_MSW=false
參考登入使用全域唯一 username，tenant 由 Server 依 Account 推導；前端不保存固定 tenant。
後端開發代理位於 vite.config.ts 的 server.proxy，不是由
VITE_API_BASE_URL 控制；請依本機 Server context path 調整 proxy target。
6. 啟動開發伺服器
# app-office 預設連接 vite.config.ts proxy 指向的真實後端
npm run dev
# 臨時改用 Mock API
VITE_MSW=true npm run dev
訪問 http://localhost:3000 查看應用程式。
方式二：從 app-office-mockup 複製
如果你只需要建立 Prototype：
git clone https://gitlab.com/appfuse/webapp/appfuse-webapps-v1.git
cp -R appfuse-webapps-v1/modules/app-office-mockup my-mockup
cd my-mockup
git init
npm install
npm run dev
app-office-mockup 僅使用 Mock API，適合需求確認階段。
方式三：從零建立（進階）
如果你希望完全自己建立專案結構：
1. 建立 Vite 專案
npm create vite@latest my-web-app -- --template react-ts
cd my-web-app
npm install
2. 安裝 AppFuse Web
WEB_TARGET_VERSION="REPLACE_WITH_EXACT_VERSION"
npm install --save-exact "@appfuse/appfuse-web@$WEB_TARGET_VERSION"
npm view "@appfuse/appfuse-web@$WEB_TARGET_VERSION" peerDependencies --json
精確版號請從當前發布線取得。安裝完成後，核對
npm 解析的 peer dependencies 是否符合該頁基線。
3. 安裝依賴
# Vite 整合
npm install -D @tailwindcss/vite vite-tsconfig-paths
# MSW (Mock API)
npm install -D msw
AppFuse Web 的執行期套件是 peer dependencies；現代 npm 會一併解析，但仍須檢查
npm install 的 peer conflict。路由套件名稱是 react-router，不是
react-router-dom。
4. 配置 Tailwind CSS
建立 src/tailwind.css：
@source "../node_modules/@appfuse/appfuse-web/lib/**/*.{ts,tsx}";
@import "tailwindcss";
Tailwind CSS 4 採 CSS-based configuration，不需要 tailwind.config.ts。
5. 配置 Vite
在 vite.config.ts 中添加 Tailwind 和路徑別名：
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';
import tsconfigPaths from 'vite-tsconfig-paths';
export default defineConfig({
plugins: [react(), tsconfigPaths(), tailwindcss()],
});
如需 @/ alias，請在 tsconfig.app.json 加入：
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"]
}
}
}
6. 參考配置
參考 app-office 配置 建立：
- Redux Store 配置
- Router 配置
- MSW 設定
- 主題配置
專案結構建議
建議的目錄結構（參考 app-office）：
my-web-app/
├── src/
│ ├── applets/ # 業務功能模組（Applet）
│ ├── components/ # 共用組件
│ ├── layouts/ # 佈局組件
│ ├── features/ # Redux slices
│ ├── services/ # API 服務層
│ ├── mocks/ # MSW mock handlers
│ ├── config/ # 應用程式配置
│ ├── routes/ # 路由配置
│ ├── nls/ # 國際化資源
│ ├── App.tsx # 主應用程式
│ └── main.tsx # 入口檔案
├── public/ # 靜態資源
├── index.html # HTML 模板
├── package.json # 專案配置
├── vite.config.ts # Vite 配置
└── tsconfig.json # TypeScript 配置
下一步
- 專案結構說明 - 了解推薦的專案組織方式
- 第一個 Applet - 建立你的第一個業務模組
- Mock API 設定 - 了解 Mock API 的使用方式
參考資源
- app-office 原始碼 - 生產環境參考實作
- app-office-mockup 原始碼 - Prototype 參考實作
- Storybook - 元件庫互動文檔