CLI

CLI là bộ công cụ dòng lệnh hỗ trợ nhà phát triển khởi tạo, phát triển, đóng gói và xuất bản Mini App trên hệ sinh thái V-App một cách nhanh chóng và tiêu chuẩn.

Cài đặt

Yêu cầu hệ thống: Node.js LTS v22+

npm

# Cài đặt global
npm install -g @v-miniapp/cli

# Hoặc cài đặt trong repo
npm install -D @v-miniapp/cli

yarn

# Cài đặt global
yarn global add @v-miniapp/cli

# Hoặc cài đặt trong repo
yarn add --dev @v-miniapp/cli

pnpm

# Cài đặt global
pnpm add -g @v-miniapp/cli

# Hoặc cài đặt trong repo
pnpm add -D @v-miniapp/cli

Sau khi cài đặt global, bạn có thể sử dụng lệnh v-miniapp-cli trực tiếp từ terminal. Nếu cài đặt trong repo, sử dụng thông qua định nghĩa scripts trong package.json.

---

Các lệnh cơ bản

Xác thực (Identity)

Để thực hiện các lệnh cần giao tiếp với VSF API (như create, dev, deploy), bạn cần đăng nhập thông qua hệ thống VID.

Đăng nhập

v-miniapp-cli login

Đăng xuất

v-miniapp-cli logout

Khởi tạo dự án

Khởi tạo dự án V-MiniApp mới. Tự động cấu hình và cài đặt các dependencies cần thiết.

v-miniapp-cli create

Phát triển (Development)

Khởi chạy môi trường giả lập (Simulator) để xem trước ứng dụng trong quá trình code.

v-miniapp-cli dev [options]

• Mini App Server: Chạy tại port 8080 - 8999.
• Simulator Server: Chạy tại port 3000 - 3999.
• Nếu muốn chỉ định port cố định, sử dụng --host-port và --remote-port. Xem thêm các options của dev

Dev command options

Flag	Giá trị	Mặc định	Mô tả
--host <host>	string	localhost	Host cho simulator dev server
--host-port <number>	number	auto	Port cho simulator dev server
--remote-host <host>	string	localhost	Host cho Mini App server
--remote-port <number>	number	auto	Port cho Mini App server
--no-open	boolean	false	Không tự động mở trình duyệt
--no-toolbar	boolean	false	Ẩn toolbar trong Simulator
--config <path>	string	–	Đường dẫn tới file Vite config

---

Đóng gói (Build)

Bundle code để sẵn sàng deploy.

v-miniapp-cli build

Xuất bản (Deployment)

Đẩy bản build của bạn lên V-App.Bạn có thể truy cập Dev Center để quản lý phiên bản cũng như xuất bản app.

v-miniapp-cli deploy

Quy trình deploy:

1. Xác thực thông tin phiên bản trong package.json và app-config.json.
2. Chạy lệnh build tự động.
3. Zip mã nguồn và tệp dist (loại bỏ các file trong .gitignore).
4. Upload lên hệ thống của V-App.

⚠️ Lưu ý: Mỗi lần deploy, version trong package.json phải lớn hơn phiên bản đã phát hành trước đó.

Bạn có thể kiểm thử app sau khi deploy tại Dev Assistant. Xem thêm quá trình quản lý phát hành V-MiniApp tại đây.

Kiểm tra hệ thống

Kiểm tra kết nối

v-miniapp-cli healthcheck

Kiểm tra trạng thái kết nối tới các dịch vụ của V-App (Auth, API, Web) để đảm bảo môi trường phát triển sẵn sàng.

Kiểm tra phiên bản CLI

v-miniapp-cli version-check

So sánh phiên bản hiện tại với phiên bản mới nhất trên NPM và phiên bản tối thiểu bắt buộc từ hệ thống để đảm bảo tính tương thích.

---

Debug mode

Flag --debug dùng để bật chế độ ghi log chi tiết, hỗ trợ debug trong quá trình phát triển và xử lý lỗi.

v-miniapp-cli [command] --debug

Khi bật --debug, CLI sẽ:

• Log chi tiết quá trình khởi tạo command
• In đầy đủ stack trace khi xảy ra lỗi

Debug mode áp dụng cho tất cả các lệnh của CLI.

---

Lưu ý quan trọng

• Để các JS API hoạt động đúng, đảm bảo appIdentifier trong app-config.json được khai báo chính xác với app bạn đã đăng ký tại Dev Center.
• Phiên bản (version) của app được lấy từ field version của package.json.