Hướng dẫn cài đặt và sử dụng drakysoft-ui

Tài liệu này ghi chú lại các bước thiết lập một dự án mới để có thể sử dụng mượt mà các thành phần (components) từ thư viện drakysoft-ui, cũng như các quy tắc tương thích quan trọng cần tuân thủ.

1. Yêu cầu tương thích (Compatibility Requirements)

Trước khi bắt đầu, hãy đảm bảo dự án của bạn đáp ứng các yêu cầu sau:

• React: Phiên bản >=18.0.0
• Next.js (Nếu dùng App Router): Cần đánh dấu "use client"; ở đầu các file sử dụng component có chứa hooks (ví dụ: AppCheckbox, AppSwitch, AppUploadFile hay các form elements có liên quan tới react-hook-form).
• Tailwind CSS: Hỗ trợ Tailwind v3 hoặc v4 (Yêu cầu phải khai báo để Tailwind có thể quét và biên dịch các class CSS từ các components của thư viện).
• TypeScript: Khuyến nghị sử dụng TypeScript để có trải nghiệm autocompletion và type-checking tốt nhất.

2. Các lệnh khởi tạo dự án mới

Nếu bạn bắt đầu một dự án mới (ví dụ với Next.js & Tailwind CSS v4), hãy chạy lệnh:

# Khởi tạo dự án Next.js (sử dụng TypeScript, App Router, Tailwind)
npx create-next-app@latest my-app --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm

# Di chuyển vào thư mục dự án
cd my-app

3. Các lệnh cài đặt thư viện & Dependencies

Để drakysoft-ui hoạt động đúng, dự án của bạn cần cài đặt thư viện này cùng với các peer dependencies của nó:

# Cài đặt drakysoft-ui và các thư viện hỗ trợ UI/Form
npm install drakysoft-ui

# Cài đặt bắt buộc các Peer Dependencies và các thư viện tiện ích bổ sung
npm install lucide-react class-variance-authority clsx tailwind-merge tailwindcss-animate react-hook-form @hookform/resolvers zod classnames

(Ghi chú: Nếu gặp lỗi xung đột version (ERESOLVE), bạn có thể cân nhắc thêm cờ --legacy-peer-deps): npm i drakysoft-ui lucide-react class-variance-authority clsx tailwind-merge tailwindcss-animate react-hook-form @hookform/resolvers zod classnames --legacy-peer-deps

4. Cấu hình Tailwind CSS (BẮT BUỘC)

Vì các components của drakysoft-ui sử dụng Tailwind CSS, bạn cần báo cho Tailwind CSS biết để quét (scan) các class nằm bên trong thư viện, nếu không giao diện sẽ bị vỡ.

👉 Nếu bạn dùng Tailwind v4 (CSS-only config)

Thêm dòng @source vào file CSS chính của bạn (ví dụ: src/app/globals.css):

@import "tailwindcss";

/* Khai báo thư mục thư viện để Tailwind v4 quét CSS */
@source "../../node_modules/drakysoft-ui";

/*... các cấu hình CSS khác ...*/

👉 Nếu bạn dùng Tailwind v3 (tailwind.config.ts)

Thêm đường dẫn cài đặt npm vào mảng content:

import type { Config } from "tailwindcss";

const config: Config = {
  content: [
    "./src/pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/components/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/app/**/*.{js,ts,jsx,tsx,mdx}",
    
    // Thêm dòng này để tailwind v3 quét class của thư viện
    "./node_modules/drakysoft-ui/dist/**/*.{js,ts,jsx,tsx,cjs,mjs}",
  ],
  theme: {
    extend: {},
  },
  plugins: [require("tailwindcss-animate")],
};
export default config;

5. Quy tắc sử dụng trong Component (Usage Rules)

Khi sử dụng các component của drakysoft-ui (Đặc biệt là những component có tương tác UI như Switch, Checkbox, Form, Upload, Input), bạn cần lưu ý:

1. Client Components trong Next.js: Các Element tương tác (thường nằm trong mục @core/app-form-elements hoặc UI Components có chứa useState, useEffect) bắt buộc phải chạy ở Client-side. Bạn phải khai báo "use client"; trên cùng của file:

   "use client"; // <=== BẮT BUỘC
      
   import React from 'react';
   import { AppCheckbox, AppSwitch, AppUploadFile } from 'drakysoft-ui';
   
   export default function MyPage() {
     return (
       <div>
         <AppSwitch label="Dark Mode" checked={true} onChange={() => {}} />
       </div>
     );
   }

2. React Hook Form: Thư viện được tích hợp cực kì sâu với react-hook-form. Đối với các Input yêu cầu validation, bạn phải chắc chắn bọc phía bên ngoài bằng <FormProvider> của react-hook-form để form context không bị lỗi (Ví dụ lỗi: useFormContext was not found).

3. Chế độ Dark/Light mode: Các biến màu css (CSS variables) thiết kế theo cơ chế của ShadcnUI/Tailwind. Bạn nên để ý kế thừa hệ thống biến màu sắc nếu thư viện sử dụng các class như bg-background, text-foreground, border-border.