@nextgrp/ui

Shared UI library dùng chung cho các app trong hệ thống NextGrp.

Khuyến nghị:

• Khi đang phát triển UI dùng chung trong nextgrp-bench → dùng dev local (packages/ui chạy npm run dev).
• Khi release chính thức cho các app → build + publish npm.

Getting Started (Dev mới / Máy mới)

Yêu cầu

• Node.js >= 20
• npm >= 9

Bước 1 — Clone repo

git clone https://github.com/huyapja/nextgrp-ui.git
cd nextgrp-ui

Bước 2 — Cài dependencies

npm install

Bước 3 — Đăng nhập npm

npm login --auth-type=legacy
# Nhập username, password, email
npm whoami  # kiểm tra đăng nhập thành công

Bước 4 — Link local để dev (không cần publish)

npm run build
npm link

Bước 5 — Link vào app muốn dev

# Ví dụ app raven
cd ~/path/to/apps/raven
npm link @nextgrp/ui

# Ví dụ app drive
cd ~/path/to/apps/drive/frontend
npm link @nextgrp/ui

Bước 6 — Bật watch mode

Mở 2 terminal:

Terminal 1 — package UI tự rebuild khi sửa:

cd ~/path/to/nextgrp-ui
npm run dev

Terminal 2 — chạy app:

cd ~/path/to/apps/raven/frontend
npm run dev

✅ Từ giờ mỗi lần sửa code trong src/, package tự rebuild và app tự nhận — không cần làm gì thêm!

Cài đặt (dùng từ npm)

npm install @nextgrp/ui

Cách dùng

Vue

import { Button, Modal } from '@nextgrp/ui/vue'
import '@nextgrp/ui/styles'

React

import { Button, Modal } from '@nextgrp/ui/react'
import '@nextgrp/ui/styles'

⚠️ Lưu ý:

Styles phải import bằng:

import '@nextgrp/ui/styles'

Không dùng:

import '@nextgrp/ui/styles.css'

Cấu trúc thư mục

src/
├─ components/
│  ├─ react/
│  │  ├─ Button.jsx
│  │  ├─ Modal.jsx
│  │  └─ index.js
│  └─ vue/
│     ├─ Button.vue
│     ├─ Modal.vue
│     ├─ modal.css
│     └─ index.js
└─ tokens/
   ├─ index.css      ← CSS variables
   ├─ mappers.js     ← Logic mapping props → Antd props
   ├─ styles.js      ← Entry point CSS bundle
   └─ theme.js       ← Antd theme config

Quy tắc cho dev

• Chỉ sửa code trong src/

• Không sửa dist/

• Nếu sửa UI dùng chung → sửa trong package này, không sửa trực tiếp từng app

• Nếu thêm component mới:

  1. Tạo file component trong src/components/vue hoặc src/components/react
  2. Export ở file index.js
  3. Nếu có CSS riêng → import vào src/tokens/styles.js

Dev local (khuyên dùng khi đang chỉnh UI)

Khi cần sửa UI và test ngay ở app con trong nextgrp-bench, không cần publish npm.

1) Chạy watch build ở package UI

cd ~/setup/bench/nextgrp-bench/packages/ui
npm run dev

npm run dev = vite build --watch Mỗi lần sửa code trong src/, package sẽ tự build lại dist/.

2) Chạy app con

cd ~/setup/bench/nextgrp-bench/apps/drive/frontend
npm run dev

Flow chuẩn khi dev local

1. Sửa code trong packages/ui/src
2. packages/ui đang chạy npm run dev
3. App con đang chạy npm run dev
4. Nếu app chưa nhận thay đổi → xóa cache Vite:

rm -rf node_modules/.vite

Build local

cd ~/setup/bench/nextgrp-bench/packages/ui
npm run build

Publish lên npm

cd ~/setup/bench/nextgrp-bench/packages/ui
git add .
git commit -m "feat: mô tả thay đổi"
npm version patch
npm run build
npm publish --access public
git push

Gợi ý version

• patch: sửa bug / chỉnh style nhỏ
• minor: thêm component / thêm tính năng mới
• major: breaking change

Sau khi publish, update ở app đang dùng

npm update @nextgrp/ui
rm -rf node_modules/.vite

Flow chuẩn khi sửa UI dùng chung

Cách 1: Dev local (khuyên dùng khi đang làm UI)

1. Sửa trong packages/ui/src
2. packages/ui chạy npm run dev
3. App consumer chạy npm run dev
4. Nếu chưa nhận thay đổi → xóa .vite

Cách 2: Publish chính thức

1. Sửa trong packages/ui/src
2. Build + publish npm
3. Sang app consumer chạy:

npm update @nextgrp/ui
rm -rf node_modules/.vite

Lỗi thường gặp

1) App không nhận export mới

• Kiểm tra đã export trong index.js chưa
• Build lại package
• Nếu đang dev local: kiểm tra packages/ui đang chạy npm run dev chưa
• Nếu đang dùng npm: publish lại rồi chạy npm update @nextgrp/ui

2) CSS không ăn / vẫn bị CSS cũ

• Kiểm tra file CSS đã được import trong src/tokens/styles.js chưa
• App đã import import '@nextgrp/ui/styles' chưa
• Xóa cache Vite: rm -rf node_modules/.vite

# Debug tìm class CSS
grep -R "tên-class-cần-tìm" -n src dist

3) Sửa ở src nhưng app vẫn chưa đổi

# Restart watch mode
cd ~/setup/bench/nextgrp-bench/packages/ui
npm run dev

# Xóa cache app
cd ~/setup/bench/nextgrp-bench/apps/drive/frontend
rm -rf node_modules/.vite && npm run dev

4) Lỗi Cannot find module '@nextgrp/ui/react'

Lỗi TypeScript — không ảnh hưởng runtime. Bỏ qua hoặc thêm vào tsconfig.json:

{
  "compilerOptions": {
    "checkJs": false
  }
}

5) Lỗi Dynamic require of "react" is not supported

Package đang bundle antd vào. Kiểm tra size:

ls -lh node_modules/@nextgrp/ui/dist/react.js
# Nếu > 100KB → cần rebuild package với external đúng

Ghi nhớ nhanh

| Việc cần làm | Lệnh | |---|---| | Dev local | npm run dev (trong packages/ui) | | Build | npm run build | | Publish | npm version patch && npm run build && npm publish --access public | | Update ở app | npm update @nextgrp/ui && rm -rf node_modules/.vite | | Xóa cache | rm -rf node_modules/.vite |