App React trên website

Bạn build app ở máy; website phục vụ bản build. Chunk, header cache, phiên bản và route phía trình duyệt là việc của nền tảng: bạn deploy dist/, một trang gắn nó bằng một tag.

webmati add react-app dashboard --route /dashboard   # app/ và pages/dashboard.json
cd app && npm install && npm run build                # dist/ + dist/.vite/manifest.json
cd .. && webmati app deploy                           # tải lên phần đổi, cho chạy thật
webmati push                                          # trang (bản nháp cho tới khi công khai)
webmati tool call publish_page --json '{"id":"dashboard"}'

Rồi mở /pages/dashboard trên website — hoặc bất kỳ địa chỉ /dashboard/… nào (route).

1. Tạo sẵn: add react-app

webmati add react-app dashboard --route /dashboard

Lệnh ghi:

• app/ — một app Vite + React + TypeScript build cho website: vite.config.ts (base: "./", build.manifest: true, entry là src/main.tsx), src/config.ts (những gì trang báo cho app), src/api.ts (backend riêng của website: đăng nhập, route, cập nhật trực tiếp), README.md và webmati.app.json (tên, thư mục build, trang, route).
• pages/dashboard.json — một trang có đúng một section App (app-mount) gắn app. Trang này push như mọi trang khác.

Mã nguồn trong app/ là file của project (xem File riêng của project): push lưu nó cho nhóm — không bao giờ phục vụ ra ngoài — và clone của người tiếp theo sẽ có nó. dist/ và node_modules/ của nó không bao giờ được gửi: khách truy cập chỉ nhận bản build, qua app deploy. App thứ hai đặt chỗ khác trong app/: webmati add react-app reports --into app/reports.

2. Deploy: app deploy

webmati app deploy

dashboard v3: live.
  6 files (412.7 KB); uploaded 1 (2.1 KB) — the rest the website already had.
  Served from /_app/dashboard/a1b2c3d4e5f6/ on the website's own domains, cached for a year (each version has its own URL).
  Not deployed: index.html (the page that mounts the app is the theme's).
  Route: every path under /dashboard renders /pages/dashboard.
  Mount it on a page with {% app 'dashboard' %} or the app-mount section — https://shop.brand.com/pages/dashboard.

• Mỗi file được băm trước; chỉ phần website chưa có mới được tải lên (song song, có thử lại), nên deploy lại sau khi đổi một chunk chỉ gửi một chunk. Khách không thấy gì đổi cho tới bước cuối, khi phiên bản được cho chạy thật.
• --no-activate tải lên mà không chuyển: phát hành sau bằng webmati app rollback dashboard <v>. --note "…" ghi phiên bản đổi gì.
• --dist DIR deploy thư mục build khác; webmati app deploy <tên> chọn một app khi dự án có nhiều app.
• Bundler khác: đưa danh sách entry bằng --manifest entries.json: {"entries":[{"file":"app.js","css":["app.css"],"imports":["chunk.js"]}]}.

Một lần deploy được chứa: js mjs css map wasm json svg png jpg jpeg gif webp avif ico woff woff2 ttf otf txt webmanifest — không bao giờ .html, .htm hay .xml (trang là của theme). Tối đa 10 MB một file, 50 MB và 2000 file một phiên bản. Bản build phạm luật bị từ chối trước khi gửi bất cứ gì.

3. Gắn vào trang

Trong theme, hoặc section bất kỳ:

{% app 'dashboard' %}
{% app 'dashboard', entry: 'src/admin.tsx', root: 'admin-root', loading: 'Đang tải…' %}

Hoặc thêm section App trong trình tuỳ biến (hay trong các section của một trang) và gõ tên app. Tag render phiên bản đang chạy: một phần tử gốc, cấu hình JSON cạnh nó, các stylesheet, <link rel="modulepreload"> cho các chunk entry import, và entry dạng <script type="module">. App chưa deploy (hoặc chưa có phiên bản chạy) render một comment HTML nói lý do — không bao giờ là lỗi.

Cấu hình (src/config.ts đọc): id và slug của website, ngôn ngữ của trang, api (backend riêng của website), base_path (gốc của router) và preview. Nó không bao giờ nói ai đang xem — trang được cache chung cho mọi người; app tự giữ phiên đăng nhập.

4. Deep link: app route

Router phía trình duyệt dẫn tới /dashboard/orders/42; khi tải lại, trình duyệt hỏi website địa chỉ đó. Một route khiến mọi đường dẫn dưới một tiền tố render trang của app:

webmati app route dashboard /dashboard      # hoặc "route" trong webmati.app.json — gắn lại mỗi lần deploy
webmati app unroute /dashboard

Đặt gốc router ở config.base_path (<BrowserRouter basename={config.base_path}>). Route là phương án cuối cùng: trang, bài viết, sản phẩm hay redirect thật ở cùng địa chỉ trả lời trước, và các đường dẫn của nền tảng (/cart, /checkout, /account, /api, /_app …) không bao giờ là route được.

5. Phiên bản và rollback

webmati app list
webmati app versions dashboard
webmati app rollback dashboard          # phiên bản ngay trước bản đang chạy (hỏi trước)
webmati app rollback dashboard 4 --yes  # một phiên bản cụ thể
webmati app rm dashboard                # mọi phiên bản và route (hỏi trước)

Website giữ phiên bản đang chạy, 10 bản mới nhất và mọi bản từng chạy trong một ngày qua — trang ai đó mở trước khi deploy vẫn tải được chunk của nó.

6. Xem trước trực tiếp khi làm: dev --app

webmati dev --app dashboard

Lệnh chạy build của app ở chế độ theo dõi (npm run watch; thêm --no-app-build nếu bạn tự chạy), deploy mỗi bản build thành một bản dev và tải lại trang xem trước, nơi hiện đúng bản đó. Bản dev không bao giờ chạy thật: khách vẫn thấy phiên bản đang chạy cho tới khi bạn app deploy.

7. Backend của app

src/api.ts nói chuyện với backend riêng của website (config.api) đúng như skill shop-backend-frontend: nút đăng nhập lấy từ /auth/config, phiên đăng nhập giữ ở trình duyệt, mọi lời gọi đi qua route của workflow (api.call("/my/todos")), cập nhật trực tiếp bằng api.listen(channel, …).