fe-osp-shared

Shared Frontend Package for Multi-Repo Architecture

Tổng quan

fe-osp-shared là package React/TypeScript dùng chung cho các frontend repo trong hệ sinh thái OSP. Đây là nền tảng trung tâm giúp đồng bộ hóa UI, logic, xác thực, theme, i18n, networking, config, test... giữa các repo FE, tối ưu cho mô hình multi-repo hiện đại.

Tính năng nổi bật & Lợi ích cho multi-repo

| Phần | Ý nghĩa & lợi ích cho multi-repo | Cụ thể sẽ làm | Package + Note | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Auth (Xác thực & Phân quyền) | Gom logic xác thực & phân quyền, tránh code lại nhiều repo, đảm bảo quản lý token & quyền thống nhất | - authBaseSlice, authState- Hook useAuth, hasPermission- tokenManager.ts quản lý token- PermissionWrapper ẩn/hiện UI theo quyền- AuthService login/logout/refresh | Package: redux toolkit, axiosNote: Đảm bảo flow refresh token; Repo con cần wrap <AppProvider> | | Theme (UI & Appearance) | Đồng bộ giao diện toàn hệ thống (Light/Dark, Ant Design + Tailwind). Đảm bảo mọi repo có UI nhất quán, đồng bộ token. | Ant Design:- themeBaseSlice- AppThemeProvider wrap toàn app- ThemeAdapter config token- theme.config.ts, themeUtils.tsTailwind:- Đồng bộ tokens trong themeSlice- Repo con mở rộng config qua presets trong tailwind.config.ts để import từ shared | Package: @ant-design/cssinjs, tailwindcss (cài tại repo con)Note: Không cài tailwindcss/vite trong shared. Mỗi repo Tailwind cần tailwind.config.ts riêng; dùng presets để gộp config từ shared. | | Config & Environment | Quản lý cấu hình theo môi trường (local/remote). Dễ scale khi nhiều repo cần cùng 1 chuẩn. | - configBaseSlice lưu config- Hook useConfig- loadConfigFromEnv (.env)- loadConfigFromRemote (BE endpoint) | Package: dotenv (Vite built-in)Note: Quy tắc load .env → .env.[mode] → .env.local (ưu tiên cao nhất) | | Common UI | Gom component UI tái sử dụng, giảm lặp code, đồng bộ UX | - Component: Loading, EmptyState, ErrorPage, NotFound- PermissionWrapper (liên quan Auth) | Package: Ant DesignNote: Wrap lại Ant Design để đồng bộ style | | i18n (Đa ngôn ngữ) | Chuẩn hóa đa ngôn ngữ, dễ scale thị trường & repo | - Tích hợp react-i18next- File dịch: locales/en.json, vi.json…- Hook useLanguage- Component LanguageSelector | Package: react-i18next, i18next-browser-languagedetectorNote: Repo con chỉ cần import hook & cac file dịch phải dat đung rule | | Networking (API & Services) | Gom chuẩn gọi API, tránh mỗi repo tự xử lý. Interceptor token thống nhất. | - apiService (axios + interceptor)- apiCall<T> với chuẩn BaseResponse<T>- notiService (wrap antd notification)- Hook onRequest/onResponse/onError | Package: axiosNote: Interceptor gắn token tự động; repo con có thể override | | Utils Functions | Gom các hàm xử lý chung, tránh viết lại. | - dateUtils, numberUtils, stringUtils, objectUtils, validateUtils, themeUtils | Package: dayjsNote: Chỉ import hàm cần dùng để tránh bundle lớn | | Testing Utils | Chuẩn hóa test, dễ mock API & render component đồng bộ | - renderWithProviders()- MSW mock API- Setup Jest + RTL | Package: jest, @testing-library/react, @testing-library/jest-dom, jest-environment-jsdom, ts-jest, mswNote: Đảm bảo test pass cho slice, hooks, services, utils |

Cấu trúc thư mục

fe-osp-shared/
├── src/
│   ├── components/         # Các component UI dùng chung
│   ├── hooks/              # Custom hooks
│   ├── services/           # Service API, notification, storage...
│   ├── store/              # Redux store, slice, typed hooks
│   ├── utils/              # Helper function, xử lý dữ liệu
│   ├── config/             # Cấu hình theme, đa ngôn ngữ
│   ├── constants/          # Hằng số dùng chung
│   ├── types/              # TypeScript types
│   └── locales/            # File ngôn ngữ
├── package.json
├── README.md
└── ...

Ứng dụng thực tế

• Tái sử dụng UI/logic: Các repo FE chỉ cần cài package này là có thể dùng lại toàn bộ component, hooks, store, service chuẩn hóa.
• Đồng bộ giao diện: Theme, ngôn ngữ, notification, error page... nhất quán trên mọi repo.
• Dễ bảo trì: Sửa đổi, nâng cấp ở shared repo sẽ tự động áp dụng cho mọi consumer repo.
• Tối ưu test: Đã có sẵn unit test cho mọi thành phần, dễ dàng CI/CD.

Đóng góp & phát triển

• Fork, PR, issue tại repo này.
• Đảm bảo test pass trước khi merge.
• Định hướng: mở rộng thêm component, service, tích hợp CI/CD, publish npm.

License

MIT