Phát triển trên máy
Trình sửa giao diện trong trang quản trị hợp cho một sửa đổi nhỏ. Khi bạn dựng cả một bộ giao diện, bạn muốn trình soạn thảo của mình, Git của mình, và thấy ngay kết quả:
xstore theme dev
Lệnh này mở http://localhost:1222 — tệp trên máy bạn, dữ liệu thật của cửa hàng. Sửa CSS,
bấm tải lại, thấy ngay. Không tải lên, không xuất bản, khách không thấy gì.
1. Cài CLI
Tải gói và cài:
npm install -g ./xstore-cli-0.1.0.tgz
xstore --version
Cần Node 20 trở lên. Cùng một CLI dùng cho cả xstore deploy (storefront Next.js) lẫn
xstore theme.
2. Lấy khoá API
Quản trị → Nhà phát triển → Khoá API → Tạo khoá.
Chọn đúng hai quyền:
| Quyền | Để làm gì |
|---|---|
template.view |
pull, list, preview |
template.manage |
check, push, activate, dev |
Khoá
sk_live_…chỉ hiện một lần. xStore lưu bản băm, nên không có cách nào xem lại — đóng cửa sổ mà chưa lưu thì phải tạo khoá mới.
Đây là khoá bí mật, khác hẳn khoá công khai pk_live_ của website: ai cầm nó làm được mọi
thứ trong phạm vi quyền đã cấp. Đừng đưa vào mã nguồn, đừng commit. Đặt vào biến môi trường:
export XSTORE_API_KEY=sk_live_…
export XSTORE_API_URL=https://api.xstore.vn
Mọi lệnh dưới đây cũng nhận --key và --api nếu bạn không muốn dùng biến môi trường.
3. Kéo theme về máy
xstore theme list
xstore theme pull --set <slug> --dir ./theme-cua-toi
→ anphatpc v4 (đang hoạt động)
→ 67 slot, 3 asset
→ ghi vào ./theme-cua-toi (71 tệp mới, 0 ghi đè)
ℹ Theme này đang phục vụ khách, nên `push` sẽ bị từ chối. Sửa slug trong theme.json để xuất bản
thành bản nháp mới.
Mỗi tệp .html là một slot — đúng cấu trúc thư mục ở trang Bắt đầu.
theme.json giữ tên và slug của bộ giao diện.
Bắt đầu từ con số không thì dùng xstore theme init <tên>: nó dựng đủ bộ slot, mỗi slot một khối
mẫu ghi rõ tên slot của chính nó — nên trang trắng vì thiếu tệp trông khác hẳn trang trắng vì
lỗi Liquid. Kèm theo là tệp THEME-NOTES.md liệt kê những chỗ Liquid của xStore không giống
Shopify. Đọc tệp đó trước khi viết template đầu tiên.
4. Vòng lặp sửa — xstore theme dev
xstore theme dev --dir ./theme-cua-toi
→ phiên dev 87nlxbt79r (hết hạn 17:25)
→ đã tải lên 67 slot
→ http://localhost:1222 sẵn sàng sau 0.1s
assets/* → đĩa cục bộ (tức thì)
còn lại → https://cua-hang-cua-ban.vn
Ctrl+C để dừng và xoá phiên.
Mở http://localhost:1222. Bạn đang xem template của bạn dựng trên sản phẩm, danh mục,
banner và thiết lập thật của cửa hàng. {{ settings.* }} và {{ custom.* }} vẫn chạy, vì
xStore lấy chúng từ bộ giao diện đang phục vụ khách — bạn không phải dựng lại dữ liệu giả.
Hai loại sửa, hai đường đi khác nhau:
| Bạn sửa | Chuyện gì xảy ra |
|---|---|
assets/* (CSS, JS, ảnh) |
không tải lên gì cả. CLI phục vụ thẳng từ đĩa. Dòng · assets/app.css (chỉ cục bộ) |
tệp .html |
đồng bộ lên phiên dev. Dòng ↻ home/index.html (45ms) |
Vì phần lớn thời gian dựng giao diện là sửa CSS, đây là chỗ vòng lặp nhanh nhất.
Cửa hàng thật không đổi. Phiên dev chỉ hiện với trình duyệt của bạn (một cookie ký HMAC),
mọi trang đều gắn noindex, nofollow và no-store, và không có gì được ghi vào bộ giao diện
đang phục vụ khách. Ctrl+C xoá phiên; nếu bạn đóng máy đột ngột, phiên tự hết hạn.
Một link xem thử đã ký luôn thắng phiên dev. Mở link xem thử trong lúc
theme devđang chạy thì bạn thấy bản được xem thử, không phải tệp trên máy — vì bấm vào một link là hành động có chủ đích, còn cookie dev thì âm thầm.
5. Kiểm tra
xstore theme check --dir ./theme-cua-toi
✔ 67 slot, 3 asset — không có vấn đề nào.
ℹ Liquid được kiểm tra về cấu trúc (thẻ cân đối, tên thẻ và bộ lọc có thật), không phải biên
dịch. Máy dựng là PHP keepsuit/liquid; chỉ bản xem thử mới thực sự chạy nó.
check không ghi gì. Nó bắt được thẻ không đóng, tên bộ lọc sai, slot lạ, asset quá lớn —
nhưng nó không phải trình biên dịch. Những lỗi chỉ bản xem thử mới lộ ra nằm ở mục Khi có lỗi
bên dưới.
6. Xuất bản bản nháp và xem thử
push từ chối ghi đè bộ giao diện đang phục vụ khách. Muốn xuất bản, đổi slug trong
theme.json thành một tên mới — xStore tạo bộ giao diện mới ở trạng thái nháp:
xstore theme push --dir ./theme-cua-toi
→ đóng gói 67 slot, 3 asset (390 KB)
→ tải lên…
→ kiểm tra… ok
→ tạo bản nháp "giao-dien-moi" v1 (id htj1cyjo14)
→ xem thử: https://cua-hang-cua-ban.vn/?_theme=htj1cyjo14&_exp=…&_sig=…
Kích hoạt: xstore theme activate --set giao-dien-moi
Link xem thử là tên miền thật của bạn cộng một chữ ký có hạn. Gửi được cho đồng nghiệp hay
khách hàng; họ không cần cài gì. Trang xem thử có dải báo "Bạn đang xem trước một giao diện chưa
xuất bản" và luôn noindex.
Lấy lại link bất cứ lúc nào bằng xstore theme preview --set <slug>.
Hãy bấm qua các trang thật sự: trang chủ, một trang sản phẩm, một trang danh mục, giỏ hàng, tìm kiếm, một trang nội dung. Đây là bước duy nhất chứng minh theme dựng được.
7. Đưa lên phục vụ khách
xstore theme activate --set giao-dien-moi
Đổi ngay, không có thời gian chờ. Bộ giao diện cũ vẫn còn nguyên — quay lại chỉ là kích hoạt lại nó:
xstore theme activate --set giao-dien-cu
Đó là đường lùi: giữ bộ giao diện đang chạy làm một set riêng, đừng xoá nó cho tới khi bản mới đã sống được vài ngày.
8. Khi có lỗi
| Bạn thấy | Nghĩa là | Bạn làm gì |
|---|---|---|
| Trang trắng, nhưng HTTP 200 | tên biến không tồn tại. Liquid dựng biến lạ thành chuỗi rỗng, không báo lỗi | thân trang là {{ content }} (không phải content_for_layout), cửa hàng là store (không phải shop) |
| CSS không được áp dụng | thiếu asset_url |
{{ 'app.css' | asset_url | stylesheet_tag }} — stylesheet_tag nhận một URL, không nhận tên tệp |
403 khi chạy lệnh |
khoá thiếu quyền | khoá cần template.view và template.manage (§2) |
push bị từ chối |
slug trùng bộ giao diện đang phục vụ khách | đổi slug trong theme.json (§6) |
| Link xem thử trả về trang thật | chữ ký hết hạn | lấy link mới: xstore theme preview --set <slug> |
✘ Phiên dev đã hết hạn |
phiên dev hết giờ; cửa hàng đang hiện theme thật | chạy lại xstore theme dev |
Sửa .html mà không thấy đổi |
phiên dev đã dừng | xem cửa sổ chạy theme dev còn dòng ↻ không |
Liquid error in thẳng vào trang |
bộ lọc chạy trên nil |
bọc null guard quanh bộ lọc, đừng chỉ default: nó — xem THEME-NOTES.md |
9. Giới hạn hiện tại
checklà lưới chắn, không phải trình biên dịch — chỉ bản xem thử mới thực sự dựng Liquid.assets/*trong phiên dev đọc từ máy bạn; asset chỉ lên máy chủ khi bạnpush.- Phiên dev có hạn giờ và có hạn mức dung lượng cho mỗi phiên.
- Không có
watchtự xuất bản:pushluôn là một hành động bạn chủ động gõ.
Dựng giao diện bằng trợ lý lập trình (Claude Code, Cursor…)? Xem Dùng trợ lý lập trình.