# Hành Trình Xây Dựng Thư Viện Component @epilot/concorde-elements: Từ Sự Đơn Giản Đến Khả Năng Mở Rộng Tối Ưu ## Mở Đầu Xây dựng một thư viện component không chỉ là công việc kỹ thuật mà còn là một hành trình đổi mới và phát triển liên tục. Trong quá trình tái thiết kế toàn diện giao diện Journeys với dự án Concorde, nhóm phát triển của chúng tôi đã nhận ra rằng việc dựa hoàn toàn vào Material UI (MUI) không còn phù hợp với các mục tiêu dài hạn. Từ đó, thư viện component mới @epilot/concorde-elements ra đời với mục tiêu vừa giữ được sự đơn giản và tính mở rộng, vừa tăng hiệu suất và khả năng tùy chỉnh về sau. Bài viết này sẽ cung cấp cái nhìn chi tiết về quá trình phát triển thư viện này, từ những thách thức ban đầu, các giải pháp được áp dụng, cho đến bài học kinh nghiệm quý giá. --- ## Tại Sao Cần Một Thư Viện Component Mới? ### Hạn Chế Của Thư Viện Hiện Tại Thư viện @epilot/journey-elements trước đây dựa trên Material UI, tuy giúp tiết kiệm thời gian phát triển nhưng lại mang theo nhiều hạn chế: - Tăng tải hiệu suất do cách xử lý style động của MUI. - Ràng buộc phiên bản React theo sự phát hành của MUI. - Giới hạn trong việc ứng dụng các tính năng hiện đại của CSS. - Phụ thuộc vào đối tượng theme của MUI khiến việc lưu trữ thiết kế tùy chỉnh gặp khó khăn. ### Tái Thiết Kế Quy Trình Tạo Design Custom Ảnh minh họa quá trình tạo design custom và hạn chế của MUI

Ảnh minh họa quá trình tạo design custom và hạn chế của MUI

Giảm sự phụ thuộc vào MUI mở ra cơ hội tăng tốc độ phát triển và mở rộng tính năng linh hoạt hơn. --- ## Tại Sao Không Dùng Các Design System Có Sẵn? Chúng tôi nhận thấy các thiết kế có sẵn thường quá cố định và nhìn chung chung, không đáp ứng triết lý phát triển linh hoạt và đơn giản mà chúng tôi hướng tới. Thay vì thay đổi toàn bộ hệ thống lớn, việc xây dựng một thư viện nhỏ gọn với khả năng mở rộng tối ưu giúp giảm thiểu rủi ro và tăng cường kiểm soát. --- ## Những Thách Thức Trong Quá Trình Phát Triển - Cần xây dựng hơn 37 component khác nhau với nhiều biến thể phức tạp. - Di chuyển toàn bộ các khối Journeys sang thiết kế mới có thể phát sinh nhiều vấn đề tích hợp. - Đảm bảo tính tương thích với các theme tùy chỉnh cũ khi chuyển đổi sang hệ thống mới. --- ## Các Giai Đoạn Phát Triển ### 1. Thử Thách Tính Tinh Khiết (Pursuit of Purity) - Tất cả component bắt đầu được xây dựng _từ đầu_ để kiểm soát tối đa từng điểm ảnh và dòng code. - Nhiều component nền tảng như Button, Link, Card, TextField, StepperInput lần lượt hoàn thiện. - **Ưu điểm:** Kiểm soát cao, code sạch. - **Nhược điểm:** Khó mở rộng, phát triển chậm, không phù hợp cho các component phức tạp như DatePicker. #### Ví dụ về Button ban đầu ```tsx import classes from './Button.module.scss'; import type { ButtonProps } from './types.ts'; // ... export const Button = forwardRef((props, ref) => { return ( ); }); ``` ### 2. Bước Ngoặt: Mô Hình Kết Hợp Headless UI & Purity - Nhận ra cách xây dựng mọi thứ từ đầu không khả thi, nhóm quyết định tận dụng các thư viện _headless UI_ — cung cấp logic và trạng thái, nhưng không kèm giao diện. - Lựa chọn 2 thư viện nổi bật: [Radix UI Primitives](https://www.radix-ui.com/primitives) và [MUI Base](https://mui.com/base-ui/). - Kết hợp linh hoạt, xây dựng giao diện tuỳ biến dễ dàng mà vẫn tận dụng được sức mạnh logic và khả năng truy cập của các thư viện này. #### Ví dụ thành phần Autocomplete sử dụng MUI Base ```tsx import { useAutocomplete } from '@mui/base/AutocompleteUnstyled'; import { forwardRef } from 'react'; import { Input, Menu, MenuItem } from '..'; export const Autocomplete = forwardRef(function Autocomplete(props, ref) { const { getRootProps, getInputProps, getListboxProps, getOptionProps, groupedOptions } = useAutocomplete({ ...props }); return (

{groupedOptions.length > 0 ? ( {groupedOptions.map((option, index) => ( {option.label} ))} ) : null}

); }); ``` Mô hình hybrid này giúp tăng tốc phát triển và tập trung vào điểm khác biệt của thư viện đồng thời bảo đảm tính nhất quán. --- ## Nguyên Tắc Chủ Đạo Đảm Bảo Thành Công ### Cấu Trúc Thành Phần Nhất Quán - Quy chuẩn thư mục: Mỗi component gồm logic (.tsx), style (.module.scss), test, type định nghĩa và export riêng biệt. - Ví dụ: | Thành phần | Chức năng | |------------------|----------------------------------| | Button.tsx | Logic xử lý component | | Button.module.scss | Styles bằng CSS Modules | | Button.test.tsx | Tests unit và tích hợp | | types.ts | Định nghĩa TypeScript | | index.ts | Export component | - Tiền tố `Concorde-` được dùng trong class HTML để dễ dàng tùy chỉnh style. ### Design Tokens & Theming - Sử dụng CSS custom properties (CSS variables) làm nền tảng cho màu sắc, spacing, typography, transitions, hình dạng. - Cho phép dễ dàng điều chỉnh theme trên toàn bộ giao diện bằng thay đổi một biến trung tâm. - Ví dụ về các biến token: ```css :root { --concorde-primary-color: #0070f3; --concorde-secondary-color: #ff7e1b; --concorde-font-family: 'Proxima-Nova', sans-serif; --concorde-spacing: 0.25rem; } ``` - Ngoài ra còn có các custom tokens dành riêng cho từng component nhằm gia tăng khả năng tùy biến. ### TypeScript: Khiên Bảo Vệ Và Tài Liệu Sống - Toàn bộ thư viện được viết bằng TypeScript. - Types được ghi chú chi tiết trực tiếp trong file, giúp developer hiểu nhanh về props ngay trong IDE. - Ví dụ về Autocomplete props: ```ts export interface AutocompleteProps extends UseAutocompleteProps { /** Thành phần nhãn hiển thị */ label?: React.ReactNode; /** Component bị vô hiệu hóa */ disabled?: boolean; // ... } ``` ### Composition: Xây Dựng Giao Diện Phức Tạp Bằng Các Thành Phần Đơn Giản - Thiết kế các component base như Input, Button, Card ... để có thể kết hợp lại thành UI phức tạp mà không làm tăng độ phức tạp code. - Ví dụ ProductTile được dựng từ Card, Image, Typography và Button: ```tsx export const ProductTile = ({ product }) => (

{product.name} {product.description}

Hành Trình Kiến Tạo @epilot/concorde-elements: Thư Viện Component Đỉnh Cao Cho Project Concorde