UAppKit là một bộ công cụ mã nguồn mở được thiết kế để tăng tốc quá trình phát triển ứng dụng web hiện đại, cung cấp thư viện thành phần UI có thể tái sử dụng, hệ thống cấu hình linh hoạt và cơ chế tích hợp dịch vụ dữ liệu hiệu quả.

Cấu trúc dự án tiêu chuẩn

Dự án thường tuân theo kiến trúc phân tầng rõ ràng nhằm đảm bảo khả năng bảo trì và mở rộng:

uappkit/
├── src/
│   ├── ui/              <!-- Các thành phần giao diện: Button, Card, Modal... -->
│   ├── views/           <!-- Các màn hình ứng dụng (React/Vue components) -->
│   ├── api/             <!-- Lớp truy vấn backend: axios wrappers, interceptors -->
│   ├── core/            <!-- Logic nghiệp vụ chung, hooks tùy chỉnh -->
│   └── index.tsx        <!-- Điểm vào chính của ứng dụng -->
├── assets/              <!-- Hình ảnh, font, biểu tượng tĩnh -->
├── configs/
│   ├── runtime.ts       <!-- Cấu hình chạy thời gian thực (base URL, feature flags) -->
│   └── build.config.ts  <!-- Cấu hình xây dựng: target browser, optimization rules -->
├── package.json
├── vite.config.ts       <!-- Thay thế webpack: cấu hình Vite cho dev server & build -->
└── README.md

Cách khởi động dự án

UAppKit sử dụng Vite làm công cụ xây dựng mặc định. Các lệnh phổ biến được định nghĩa trong package.json:

"scripts": {
  "dev": "vite",
  "build": "tsc && vite build",
  "preview": "vite preview"
}

Để bắt đầu phát triển cục bộ:

1. Cài đặt phụ thuộc: pnpm install (hoặc npm install)
2. Chạy máy chủ phát triển: pnpm dev
3. Mở trình duyệt tại http://localhost:5173

Cấu hình môi trường

Tệp configs/runtime.ts quản lý các tham số khác nhau giữa các môi trường:

export const APP_CONFIG = {
  API_ENDPOINT: import.meta.env.VITE_API_URL || 'https://staging.api/uapp',
  ENABLE_ANALYTICS: import.meta.env.VITE_ENABLE_TRACKING === 'true',
  DEFAULT_THEME: 'light'
} as const;

Các giá trị được đọc từ biến môi trường tại thời điểm biên dịch thông qua import.meta.env, giúp tách biệt cấu hình giữa môi trường phát triển và sản xuất mà không cần thay đổi mã nguồn.

Tích hợp thành phần UI

Thư viện UI được tổ chức dưới dạng các module độc lập. Ví dụ, để sử dụng nút hành động với trạng thái tải:

import { PrimaryButton } from '@/ui/buttons';

function Dashboard() {
  const [loading, setLoading] = useState(false);

  const handleSubmit = async () => {
    setLoading(true);
    await fetch('/api/submit', { method: 'POST' });
    setLoading(false);
  };

  return <PrimaryButton 
    onClick={handleSubmit} 
    disabled={loading}
    label={loading ? 'Đang xử lý...' : 'Gửi dữ liệu'} 
  />;
}

Các thành phần này hỗ trợ theme động, hỗ trợ accessibility (ARIA), và tương thích với cả React 18 và phiên bản mới hơn.