@vetc-miniapp/cli

CLI cho VETC MiniApp (track Web/WebView, JS Bridge) — phục vụ dev loop: create → dev → build. Xem spec đầy đủ (specs/000-reconcile-existing-infra/, specs/001-project-scaffold/, specs/002-local-dev-loop/) cho quyết định thiết kế + lý do.

Cài đặt

npm install -g @vetc-miniapp/cli
# hoặc dùng trực tiếp qua npx, không cần cài global — luôn thêm @latest để tránh
# npx cache lại bản cũ (đã có tiền lệ thật: phải bump 0.1.0 → 0.1.3 liên tiếp)
npx @vetc-miniapp/cli@latest create my-app

Sử dụng

vetc-miniapp create my-app     # sinh project React mới, phụ thuộc @vetc-miniapp/apis + @vetc-miniapp/ui-react
cd my-app
vetc-miniapp dev                # vite dev server (host: true bắt buộc) + tự in QR terminal
vetc-miniapp dev --no-qr        # tắt QR terminal
vetc-miniapp dev --port 4000    # đổi port
vetc-miniapp dev --host <ip>    # ghi đè LAN IP tự detect (máy có nhiều network interface)
vetc-miniapp build               # validate app-config.json + vite build production
vetc-miniapp qr --port 4000     # in lại QR cho dev server ĐÃ CHẠY SẴN (terminal khác, hoặc
                                 # server khởi động bằng dev --no-qr lúc đầu) — không tự
                                 # khởi động gì, --port phải khớp server thật (mặc định 5173)

# Project CÓ SẴN, không phải do `create` sinh (vd project cũ, hoặc project dùng framework
# khác) — thêm đúng app-config.json còn thiếu để `dev`/`qr` in được QR, không đụng gì khác:
vetc-miniapp init --app-identifier com.vetc.demo

Quét QR bằng VETC App thật (cùng mạng LAN, tài khoản có quyền isDeveloper cho appIdentifier tương ứng) để load thẳng dev server lên thiết bị — không cần build/deploy.

Project dùng bundler khác Vite (webpack, react-scripts/Create React App)

vetc-miniapp dev chạy Vite thật — không tương thích trực tiếp với project webpack/CRA (index.html gốc không có thẻ <script>, bundler đó tự tiêm lúc build/serve thật). Nếu phát hiện webpack.config.* hoặc dependency react-scripts, dev tự động chạy hộ script dev/start thật của project (yarn dev/npm start/...) ngay — đối xử y hệt Vite, không hỏi confirm gì cả — tự dò port từ output, rồi in QR đúng port đó, không cần tự mở terminal thứ 2.

vetc-miniapp dev
# ⚠ Phát hiện project dùng webpack (webpack.config.*)...
# ▶ Đang chạy "yarn dev"...
# (log thật của yarn dev, rồi QR in ngay khi dò được port — không hỏi gì, chạy thẳng)

app-config.json

Sinh tự động bởi create, nằm ở root project:

{
  "app": { "appIdentifier": "", "name": "my-app", "version": "0.1.0" },
  "permissions": [],
  "build": { "outDir": "dist" }
}

• appIdentifier — để trống tới khi đăng ký trên hệ thống quản trị nội bộ VETC. build không bắt buộc field này có giá trị.
• permissions — mã quyền thiết bị (CAMERA/LOCATION/MICROPHONE/PHOTO_LIBRARY/ CONTACTS/BLUETOOTH/NFC/SPEECH_RECOGNIZER) — chỉ mang tính tài liệu hoá, không tự enforce quyền lúc runtime (quyền thật do backend + GrowthBook quyết định).

Phát triển

pnpm install
pnpm --filter @vetc-miniapp/cli run build
pnpm --filter @vetc-miniapp/cli test

build = tsc --noEmit (type-check) rồi esbuild gộp toàn bộ src/**/*.ts + minify thành 1 file dist/bin.js (esbuild.config.mjs) — mục đích chỉ để khó đọc source hơn khi publish lên npm, không phải bảo mật thật (JS minify vẫn chạy được, de-minify lại gần đúng bằng prettier). dependencies thật (vite/ajv/commander/prompts/qrcode-terminal/ create-template) để external, không gộp chung — vite tự kéo esbuild với native binary theo platform, gộp chung dễ vỡ vì dynamic require load binary không khớp file bundle.

Phạm vi

Chỉ track Web/WebView (JS Bridge) — không phải Native Flutter Mini App (cp_vetc_minipp_core). deploy/login/logout/healthcheck/version-check chưa được thiết kế/triển khai ở version này.