Điều kiện
- Tài khoản Pancake là thành viên của shop, có quyền quản lý cấu hình (owner hoặc người được cấp quyền).
- Node.js 22 trở lên (khuyên dùng 24).
- Biết Preact cơ bản (hoặc React nếu làm trang iframe). Nếu vibe-code, kết nối công cụ AI với MCP server theo Làm app với AI, hoặc cho nó đọc file
/developers/apps/llms-full.txt.
1. Tạo dự án
npx create-pos-app my-app
cd my-app
npm installCấu trúc mặc định:
my-app/
├─ pos-app.json # manifest: quyền, domain ngoài, danh sách extension
├─ extensions/ # code chạy trong worker (Worker UI hoặc headless)
│ ├─ order-block.tsx
│ ├─ order-summary.ts
│ └─ report.tsx # trang Worker UI mẫu theo Màn hình chuẩn
├─ page/ # trang iframe (tuỳ chọn), Vite + React
│ ├─ index.html
│ ├─ tsconfig.json # TypeScript riêng cho React
│ └─ src/main.tsx
├─ public/ # ảnh cho pos-image (tuỳ chọn)
├─ AGENTS.md # quy tắc cho công cụ AI, sinh sẵn từ template
├─ eslint.config.js # luật kiểm tra code, editor báo lỗi khi gõ
├─ package.json
└─ tsconfig.jsonTemplate khai báo sẵn các gói sau, cài bằng npm install:
@pancake-pos/ui-extensions: SDK, khai báo type cho đối tượngposvà các elementpos-*.@pancake-pos/ui: component cùng tên với elementpos-*(PosPage,PosTable…),PosProvider, theme và token của POS, dùng cho trang iframe (Giao diện trang iframe).@pancake-pos/app-cli: lệnhpos-app.@pancake-pos/eslint-plugin: luật kiểm tra code, dùng chung vớipos-app check.
Chi tiết từng gói, cấu hình TypeScript và đầy đủ lệnh CLI: SDK & CLI.
2. Khai báo extension
Ví dụ thêm một block vào form đơn và một action vào menu thao tác đơn:
{
"handle": "my-app",
"name": "App của tôi",
"version": "0.1.0",
"api_version": "2026-01",
"access": { "methods": ["GET", "PUT"] },
"extensions": [
{ "target": "order.details.block", "id": "order-block", "module": "extensions/order-block.tsx" },
{
"target": "order.details.action",
"id": "push-erp",
"label": "Đẩy sang ERP",
"presentation": "headless",
"module": "extensions/push-erp.ts"
}
]
}Xem đầy đủ trường tại Manifest và danh sách vị trí tại Extension point.
3. Chạy thử với POS
Kết nối CLI với POS (một lần cho mỗi máy):
npx @pancake-pos/app-cli loginTrình duyệt mở trang Kết nối CLI của POS: đối chiếu mã với mã trong terminal, chọn các cửa hàng (cần quyền Cấu hình ở cửa hàng đó) rồi bấm Cho phép. Chưa đăng nhập POS thì trang đưa qua đăng nhập trước. Máy không có trình duyệt hay CI dùng token tạo tay (Quản lý ứng dụng › Kết nối CLI).
Sau đó chạy:
npm run dev # build theo dõi thay đổi, phục vụ tại http://localhost:5174Trên cùng trang quản lý, bấm Chế độ phát triển và nhập http://localhost:5174 (xem Quản lý ứng dụng › Chế độ phát triển). Khi bật, POS nạp app từ localhost chỉ trong trình duyệt của bạn; người khác trong shop vẫn dùng version đang kích hoạt. Sửa code thì POS tự nạp lại extension, không phải tải lại trang. Dùng Chrome hoặc Edge: Safari có thể chặn trang https nạp từ http://localhost.
Ở chế độ phát triển, pos.api chỉ gọi được Open API khi app đã upload ít nhất một lần (npm run deploy, không cần kích hoạt), và dùng access của version upload gần nhất. Đổi access thì deploy lại. Sau mỗi lần deploy như vậy, tải lại trang POS để POS lấy token mới.
Chế độ phát triển chạy với dữ liệu thật của shop đang mở, nên thử trên shop test trước. Muốn xem app với tài khoản nhân viên quyền hẹp, deploy và kích hoạt trên shop test rồi đăng nhập bằng tài khoản đó.
Trong lúc viết code, editor có extension ESLint báo lỗi ngay khi gõ. Chạy npm run check để kiểm tra cả manifest.
4. Đóng gói và upload
npm run deployLệnh này:
- Chạy
pos-app check: kiểm tra manifest và các lỗi hay gặp trong code (xem SDK & CLI). - Build từng module trong
extensions/thành một file ES module độc lập, build trangpage/bằng Vite. - Kiểm tra lần cuối: target hợp lệ, file tồn tại, kích thước trong giới hạn.
- Upload và tạo version mới ở trạng thái chưa kích hoạt, in ra mã version.
5. Kích hoạt
Trên trang Ứng dụng tuỳ biến, quản trị viên của shop:
- Bấm Phiên bản ở dòng của app (app mới: Duyệt & kích hoạt), rồi Kích hoạt ở version vừa upload.
- Xem quyền dữ liệu (
access), máy chủ bên ngoài (network.allowed_origins) và vị trí hiển thị app yêu cầu, rồi bấm Kích hoạt. Người dùng thấy extension ở lần tải trang kế tiếp.
Mặc định mọi thành viên của shop đều thấy app; giới hạn theo bộ phận chưa có trên trang quản lý. Quay về version cũ, tắt app, xem nhật ký lỗi: Quản lý ứng dụng trong POS.
Bước tiếp theo
- Quản lý ứng dụng trong POS: kích hoạt, bật tắt, xem lỗi.
- Làm app với AI: MCP server và câu lệnh mẫu.
- Ví dụ: app mẫu hoàn chỉnh.
- Runtime API: đối tượng
pos. - Component giao diện: element
pos-*.

