📦 Common UI Library

Document Version: 1.0

Status: 🟢 Stable

@nhatdev94/common-ui là thư viện UI component dùng chung, giúp chuẩn hóa giao diện, giảm thiểu trùng lặp code và đảm bảo tính nhất quán cho toàn bộ hệ sinh thái frontend.

1️⃣ Hướng dẫn tích hợp cho dự án mới

Để sử dụng thư viện trong các dự án (Vite, Next.js, v.v.), vui lòng thực hiện các bước sau:

Cài đặt package

npm install @nhatdev94/common-ui

Thiết lập Styles & Themes

Mở file CSS chính (ví dụ: src/index.css hoặc app/globals.css) và cấu hình:

@import "tailwindcss";

/* -----------------------------------------------------------
 * IMPORT THEME
 * Cung cấp màu sắc, biến CSS nền và thiết lập layout cơ bản.
 * ----------------------------------------------------------- */
@import "@nhatdev94/common-ui/themes/default.css";

/* Chỉnh sửa đường dẫn đến node_modules của bạn */
@source "../node_modules/@nhatdev94/common-ui/dist/**/*.js";

2️⃣ Hướng dẫn sử dụng Components

Thư viện được xây dựng theo tư duy Atomic Design, đảm bảo các component là Stateless by default và Business-agnostic.

Storybook

npm run storybook

Component

import { Button } from '@nhatdev94/common-ui'

export default async function DemoPage() {
  return (
    <Button>Click Me<Button>
  )
}

• Data Table

// app/payments/columns.tsx
// Định nghĩa Column

"use client"

import { ColumnDef } from "@tanstack/react-table"

export type Payment = {
  id: string
  amount: number
  status: "pending" | "processing" | "success" | "failed"
  email: string
}

export const columns: ColumnDef<Payment>[] = [
  {
    accessorKey: "status",
    header: "Status",
  },
  {
    accessorKey: "email",
    header: "Email",
  },
  {
    accessorKey: "amount",
    header: "Amount",
  },
]

Tiếp theo, chúng ta sẽ tạo component để hiển thị bảng của mình.

// app/payments/page.tsx

import { columns, Payment } from "./columns"
import { DataTable } from "@nhatdev94/common-ui"

export default async function DemoPage() {
  const data: Payment[] = [
    {
      id: "728ed52f",
      amount: 100,
      status: "pending",
      email: "[email protected]",
    },
    // ...
  ]   
 
  return (
    <div className="container mx-auto py-10">
      <DataTable columns={columns} data={data} />
    </div>
  )
}

3️⃣ Quy trình cập nhật và nâng cấp Package

Các quy tắc (Rules) cần tuân thủ

Để đảm bảo tính ổn định, mọi đóng góp phải tuân thủ:

• Naming: Sử dụng PascalCase cho tên component và kebab-case cho tên file.

• No Side Effects: Tuyệt đối không gọi API hoặc chứa logic nghiệp vụ (Business logic).

• Independence: Không phụ thuộc vào Redux, Zustand hoặc App Context của dự án tích hợp.

• Naming Props: Interface cho props phải có định dạng ComponentNameProps.

Quy trình thực hiện (Workflow)

Giai đoạn 1: Cập nhật tại Package (Pkg Side)

• Modify Code: Chỉnh sửa source code trong src/components.

• Test: Chạy unit test và kiểm tra trên npm run storybook.

• Bump Version: Cập nhật phiên bản trong package.json theo chuẩn SemVer:

• PATCH: Sửa lỗi nhỏ.
• MINOR: Thêm tính năng mới (tương thích ngược).
• MAJOR: Thay đổi lớn (không tương thích ngược).

• Build & Publish: Chạy npm run build và đẩy lên registry bằng npm publish.

Giai đoạn 2: Tích hợp vào Ứng dụng (App Side)

• Upgrade: Chạy lệnh npm install @nhatdev94/common-ui@latest.

• Regression Test: Kiểm tra lại các module liên quan để đảm bảo không có lỗi phát sinh.