@retion-miniapp/cli

Build và deploy web mini app lên app Retion.

npm i -D @retion-miniapp/cli

npx retion-miniapp init --app-id <app_id> --name "<Tên>"   # 1 lần / project
npx retion-miniapp login                                   # 1 lần / máy
npx retion-miniapp deploy                                  # mỗi lần cập nhật

deploy:  tăng version ─▶ build ─▶ đóng gói zip ─▶ upload ─▶ channel testing
                                                               │
Console: bấm "→ production" ───────────────────────────────────┴─▶ người dùng nhận ở lần mở kế tiếp

init

Tạo miniapp.config.json cho project. Chạy 1 lần, commit file này cùng source.

npx retion-miniapp init --app-id my-mini-app --name "My Mini App"

| Tuỳ chọn | Bắt buộc | Ý nghĩa | |---|---|---| | --app-id | Nên có | app_id của mini app trên Console (= app_id của widget). Bỏ trống → lấy từ name trong package.json | | --name | Không | Tên hiển thị. Bỏ trống → dùng app_id |

Tự thêm .retion/ (thư mục chứa zip build ra) vào .gitignore. Project Vite: lệnh build được đặt sẵn kèm --base=./ (mini app chạy từ file trong máy nên asset phải dùng đường dẫn tương đối) — không cần sửa vite.config.

login

Lưu deploy token của app để deploy dùng. Chạy 1 lần mỗi máy, mỗi app.

npx retion-miniapp login
# Deploy token: ········        ← dán token (không hiện ký tự)
# ✔ Đã đăng nhập "My Mini App" (my-mini-app)

• Lấy token: Console → app → Cấp lại deploy token.
• Token được kiểm tra với Platform ngay — sai / app chưa tạo là báo luôn.
• Lưu ở ~/.retion/credentials.json (chỉ user của bạn đọc được), theo từng app_id — nhiều mini app trên 1 máy không lẫn nhau.
• app_id lấy từ miniapp.config.json của thư mục hiện tại → chạy trong đúng project.

whoami — xem project hiện tại đã đăng nhập chưa. logout — xoá token đã lưu.

deploy

Tăng version → build → đóng gói → upload lên channel testing.

npx retion-miniapp deploy --note "Sửa UI header"
# ● [email protected] (từ 0.3.4) → testing
# ✔ Build xong
# ✔ .retion/demo-miniapp-0.3.5.zip · 27.2 KB · 3 file
# ✔ Đã deploy [email protected] lên "testing"

| Tuỳ chọn | Mặc định | Ý nghĩa | |---|---|---| | --note "<text>" | — | Ghi chú, hiện trong lịch sử version trên Console | | --channel testing\|production | testing | testing: chỉ bản app dev nhận. production: mọi người dùng nhận ngay (bỏ qua bước promote) | | --bump patch\|minor\|major\|none | patch | Cách tăng version — xem Version | | --dry-run | — | Build + đóng gói thử. Không đổi version, không upload |

Lỗi ở bất kỳ bước nào → version tự trả về như cũ.

Sau khi deploy lên testing: Console → version → → production để phát hành cho người dùng. Chọn version cũ → → production để rollback.

build / pack

Dùng khi muốn kiểm tra output mà không deploy.

| Lệnh | Làm gì | |---|---| | build | Chạy lệnh build trong config, kiểm tra output chạy được trong app | | pack | Đóng gói outDir → .retion/<app_id>-<version>.zip + manifest.json (không upload) |

Version

deploy tự tăng version trong miniapp.config.json — không sửa tay.

| Lệnh | 0.3.4 thành | Dùng khi | |---|---|---| | deploy | 0.3.5 | Sửa lỗi, chỉnh UI | | deploy --bump minor | 0.4.0 | Thêm tính năng | | deploy --bump major | 1.0.0 | Thay đổi lớn | | deploy --bump none | 0.3.4 | Upload lại đúng version hiện tại (vd lần trước lỗi mạng) |

App so version để quyết định tải bản mới: version mới được tải nền ở lần mở mini app, áp dụng ở lần mở sau.

miniapp.config.json

{
  "app_id": "my-mini-app",
  "name": "My Mini App",
  "version": "0.3.4",
  "outDir": "dist",
  "build": "npm run build -- --base=./",
  "entry": "index.html"
}

| Field | Ý nghĩa | |---|---| | app_id | Mini app trên Console — quyết định deploy vào đâu | | name | Tên hiển thị | | version | SemVer x.y.z — deploy tự tăng | | outDir | Thư mục output của lệnh build (Vite: dist) | | build | Lệnh build web | | entry | File HTML trong outDir (thường index.html) |

Yêu cầu với output build: asset dùng đường dẫn tương đối. init đã lo việc này cho project Vite (--base=./); build báo lỗi nếu còn thấy src="/...".

Lỗi thường gặp

| Thông báo | Cách xử lý | |---|---| | Chưa đăng nhập deploy cho "<app_id>" | npx retion-miniapp login | | Token không đúng cho app "<app_id>" | Console → app → Cấp lại deploy token → login lại | | App "<app_id>" chưa được tạo trên Console | Tạo app trên Console với đúng app_id trong miniapp.config.json | | Version x.y.z đã tồn tại trên server | Deploy lại không kèm --bump none | | ... tham chiếu asset bằng đường dẫn tuyệt đối | Đổi build trong miniapp.config.json thành npx vite build --base=./ | | Bundle ... vượt giới hạn | Bỏ file lớn (video, ảnh gốc) khỏi build | | command not found: retion-miniapp | Dùng npx retion-miniapp ... (CLI cài trong project) |

Script trong package.json: đừng đặt tên login / pack — trùng lệnh có sẵn của yarn/npm. Dùng "miniapp:deploy": "retion-miniapp deploy".

Dùng trong web: @retion-miniapp/sdk.

Phát triển CLI

npm i
npm run check           # typecheck + lint + test + build + publint
npm run release:minor   # ghi CHANGELOG mục "## Unreleased" trước

License

MIT