MAINAM Super App CLI

CLI hỗ trợ dự án React Native trong hệ sinh thái MAINAM Super App.

Tool này đang làm 3 việc chính:

• đăng nhập vào dịch vụ phát hành bundle
• chạy Metro kèm QR để thiết bị mobile lấy bundle dev
• build bundle React Native cho android và ios, sau đó có thể publish lên App Center nội bộ

Tài liệu nên đọc

• Mô hình hệ thống Super App - Miniapp - CLI

Phạm vi của repo

Repo này chỉ chứa CLI Node.js phát hành với tên lệnh:

mn-super-app-cli

CLI được thiết kế để chạy bên trong một project React Native, không phải chạy độc lập ở thư mục bất kỳ.

Yêu cầu môi trường

Trước khi dùng CLI, máy cần có:

• Node.js và npm
• React Native CLI khả dụng từ terminal qua lệnh react-native
• một project React Native có index.js và app.json
• kết nối mạng tới server App Center / Miniapp backend mà bạn cấu hình

Self-host và multi-server

Từ version CLI hiện tại, tool hỗ trợ nhiều server profile và nhiều tài khoản độc lập theo từng server.

Các lệnh chính:

mn-super-app-cli server add local https://mini.local.company
mn-super-app-cli server add prod https://mini.company.com
mn-super-app-cli server list
mn-super-app-cli server use local
mn-super-app-cli server current
mn-super-app-cli whoami

Nguyên tắc hoạt động:

• mỗi server có baseUrl riêng
• mỗi server có token đăng nhập riêng
• login, publish, qr luôn chạy theo server đang active
• config cũ dùng https://api-mini.isofh.com sẽ được migrate sang profile default

Cài đặt

Cài từ source của repo này

Trong repo hiện tại:

npm install
npm run start

Lưu ý: script npm run start của repo này không chạy Metro. Nó đóng gói package rồi cài global bản CLI hiện tại lên máy.

Sau khi cài xong, bạn có thể gọi:

mn-super-app-cli

Cài như package global

Nếu publish package lên registry nội bộ hoặc npm, cách dùng kỳ vọng là:

npm install -g mn-super-app-cli

Cấu trúc project React Native cần có

CLI đọc thông tin từ app.json của project React Native đang đứng tại đó.

Ví dụ tối thiểu:

{
  "name": "MainamSuperAppModule",
  "appId": "your-app-id-on-isofh-app-center"
}

Ý nghĩa:

• name: dùng khi generate QR cho chế độ dev
• appId: dùng khi publish bundle hoặc lấy QR của bản đã phát hành

Nếu thiếu app.json, CLI sẽ dừng và báo lỗi.

Cách dùng

1. Cấu hình server

Thêm server mới:

mn-super-app-cli server add <name> <baseUrl>

Ví dụ:

mn-super-app-cli server add local https://mini.local.company
mn-super-app-cli server add prod https://mini.company.com

Xem danh sách server:

mn-super-app-cli server list

Chuyển server đang dùng:

mn-super-app-cli server use local

Xem server hiện tại:

mn-super-app-cli server current

Xóa server:

mn-super-app-cli server remove <name>

2. Đăng nhập

mn-super-app-cli login

CLI sẽ hỏi:

• username của server hiện tại
• password của server hiện tại

Sau khi đăng nhập thành công, token được lưu bằng configstore trên máy local theo đúng server đang active để tái sử dụng cho các lệnh cần xác thực.

Kiểm tra user hiện tại:

mn-super-app-cli whoami

3. Đăng xuất

mn-super-app-cli logout

Lệnh này xóa thông tin đăng nhập của server đang active.

4. Chạy Metro + in QR dev

mn-super-app-cli start

Hoặc custom port:

mn-super-app-cli start 8088

Lệnh này sẽ:

• lấy danh sách IP nội bộ của máy và thêm localhost
• đọc name từ app.json
• in URL bundle cho Android/iOS
• render QR ngay trong terminal
• chạy react-native start --port <port>

QR dev chứa dữ liệu dạng JSON:

{
  "bundleAndroid": "http://<ip>:<port>/index.bundle?platform=android&dev=true&minify=false",
  "bundleIOS": "http://<ip>:<port>/index.bundle?platform=ios&dev=true&minify=false",
  "bundleName": "<name-from-app.json>"
}

5. Build bundle local

Build cả 2 nền tảng:

mn-super-app-cli build

Chỉ build Android:

mn-super-app-cli build android

Chỉ build iOS:

mn-super-app-cli build ios

Lệnh build sẽ:

• chạy react-native bundle
• tạo thư mục build/android hoặc build/ios
• sinh file index.bundle và assets tương ứng
• nén thành build/android.zip và/hoặc build/ios.zip

Tham số hợp lệ cho build chỉ có:

• android
• ios
• bỏ trống để build cả hai

6. Publish bundle

Publish theo appId trong app.json:

mn-super-app-cli publish

Hiện tại CLI sẽ:

1. kiểm tra trạng thái đăng nhập
2. dùng baseUrl của server đang active
3. đọc appId từ app.json nếu bạn không truyền đối số
4. build lại bundle cho cả android và ios
5. upload 2 file zip lên API release
6. in QR của bản release ra terminal

Bạn cũng có thể truyền appId trực tiếp:

mn-super-app-cli publish your-app-id

QR release chứa dữ liệu dạng JSON:

{
  "bundleAndroid": "https://<active-server-base-url>/api/app/<android-id>",
  "bundleIOS": "https://<active-server-base-url>/api/app/<ios-id>",
  "appIcon": "<logo-url>",
  "appName": "<app-name>",
  "bundleName": "<module-name>",
  "appId": "<app-id>"
}

Nếu backend trả sẵn full URL bundle trong response, CLI sẽ dùng trực tiếp URL đó thay vì tự ghép theo pattern /api/app/<id>.

7. Lấy lại QR của bundle đã publish

mn-super-app-cli qr

Lệnh này yêu cầu:

• đã login
• project hiện tại có app.json
• app.json có appId

CLI sẽ gọi API để lấy thông tin bundle mới nhất của app rồi in QR release ra terminal.

Luồng dùng phổ biến

Phát triển local

mn-super-app-cli start

Mở app mobile, scan QR và tải bundle dev từ máy đang chạy Metro.

Tạo bundle kiểm thử

mn-super-app-cli build

Sau khi chạy xong, kiểm tra thư mục:

build/

Publish bản mới

mn-super-app-cli server use local
mn-super-app-cli login
mn-super-app-cli publish

Hành vi theo nền tảng

• Trên macOS/Linux, CLI gọi trực tiếp react-native
• Trên Windows, CLI gọi thông qua file rn.bat

File rn.bat chỉ làm một việc: chuyển vào thư mục project hiện tại rồi chạy lại lệnh react-native.

Các điểm cần lưu ý

• CLI luôn chạy theo thư mục hiện tại (process.cwd()), nên cần đứng đúng root của project React Native
• publish hiện tại build lại cả android và ios, không có tùy chọn chỉ publish một nền tảng
• nếu đã login trước đó trên server hiện tại, login sẽ báo tài khoản hiện tại và không hỏi lại
• thông tin đăng nhập được lưu local bằng configstore theo từng server
• profile default được tạo ra để tương thích với config cũ dùng https://api-mini.isofh.com
• output build cũ trong thư mục build/ sẽ bị xóa trước khi build/publish

Phát triển CLI

Cài dependencies

npm install

Cài bản local vào máy để test nhanh

npm run start

Script này sẽ:

1. npm pack
2. npm install -g file tgz vừa tạo
3. xóa file tgz tạm

File chính

• cli.js: toàn bộ logic command line
• rn.bat: wrapper cho Windows
• package.json: metadata package và lệnh cài local

Phiên bản hiện tại

Theo package.json, version hiện tại là 1.0.4.