建立新專案

本指南說明如何從 app-web 或 app-web-mockup 參考實作建立新的 React 專案。

選擇起點

AppFuse 提供兩個前端參考實作：

專案	使用時機	API
app-web-mockup	Prototype 開發、需求確認	Mock API (MSW)
app-web	生產環境開發	支援 Mock → 真實 API 漸進切換

建議：從 app-web 開始，因為它支援 Mock API 與真實 API 的彈性切換。

方式一：從 app-web 複製（推薦）

1. 複製專案

# 複製參考實作
git clone https://gitlab.com/appfuse/webapp/appfuse-webapps-v1.git my-web-app
cd my-web-app

# 移除原始 Git 歷史
rm -rf .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-web 包含花店管理系統的示範資料，建議保留結構但清空業務邏輯：

# 移除示範 Applets
rm -rf src/applets/products
rm -rf src/applets/orders
# 保留 admin、settings 等基礎 applets

# 移除示範 Mock Handlers
rm -rf src/mocks/handlers/products
rm -rf src/mocks/handlers/orders
# 保留 auth、tenant 等基礎 handlers

5. 更新應用程式配置

編輯 src/config/app.config.ts：

export const appConfig = {
  name: 'My Web App',
  version: '0.0.1',
  apiBaseUrl: import.meta.env.VITE_API_BASE_URL || 'http://localhost:8080',
  // ...其他配置
};

6. 啟動開發伺服器

# 使用 Mock API（預設）
npm run dev

# 連接真實後端 API
VITE_API_BASE_URL=http://localhost:8080 npm run dev

訪問 http://localhost:5173 查看應用程式。

方式二：從 app-web-mockup 複製

如果你只需要建立 Prototype：

git clone https://gitlab.com/appfuse/webapp/appfuse-webapps-v1.git my-mockup
cd my-mockup
npm install
npm run dev

app-web-mockup 僅使用 Mock API，適合需求確認階段。

方式三：從零建立（進階）

如果你希望完全自己建立專案結構：

1. 建立 Vite 專案

npm create vite@latest my-web-app -- --template react-ts
cd my-web-app
npm install

2. 安裝 AppFuse Web

npm install @appfuse/appfuse-web

3. 安裝依賴

# Tailwind CSS
npm install -D tailwindcss@next @tailwindcss/vite@next

# Redux Toolkit
npm install @reduxjs/toolkit react-redux

# React Router
npm install react-router-dom

# MSW (Mock API)
npm install -D msw

# 其他工具
npm install react-hook-form date-fns

4. 配置 Tailwind CSS

建立 tailwind.config.ts：

import type { Config } from 'tailwindcss';

export default {
  content: [
    './index.html',
    './src/**/*.{js,ts,jsx,tsx}',
    // 掃描元件庫原始碼
    './node_modules/@appfuse/appfuse-web/lib/**/*.{ts,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
} satisfies Config;

建立 src/tailwind.css：

@import "tailwindcss";

/*
 * 掃描元件庫的原始碼，讓 Tailwind 統一生成 CSS
 */
@source "../node_modules/@appfuse/appfuse-web/lib/**/*.{ts,tsx}";

5. 配置 Vite

在 vite.config.ts 中添加 Tailwind 和路徑別名：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';
import path from 'path';

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});

6. 參考配置

參考 app-web 配置 建立：

• Redux Store 配置
• Router 配置
• MSW 設定
• 主題配置

專案結構建議

建議的目錄結構（參考 app-web）：

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 配置
├── tailwind.config.ts     # Tailwind 配置
└── tsconfig.json          # TypeScript 配置

下一步

• 專案結構說明 - 了解推薦的專案組織方式
• 第一個 Applet - 建立你的第一個業務模組
• Mock API 設定 - 了解 Mock API 的使用方式

參考資源

• app-web 原始碼 - 生產環境參考實作
• app-web-mockup 原始碼 - Prototype 參考實作
• Storybook - 元件庫互動文檔