manh.run hoạt động thế nào
Từ một cây thư mục app/, manh.run dựng giao diện React, API và database SQLite riêng của app. Agent viết code, còn manh.run kiểm lỗi, chạy thử và deploy.
Manh là framework full-stack cho app nội bộ và app quản trị. manh.run là dịch vụ chạy framework đó: lưu code, kiểm lỗi, hiện bản chạy thử và đưa app lên chạy thật. manh.run không có AI riêng. Người viết code là agent của bạn (Claude Code, Claude, ChatGPT, Gemini…), làm việc qua MCP.
Một cây thư mục, ba phần của app
Cấu trúc thư mục chính là cấu hình, không cần bảng route. Muốn thêm tính năng thì thêm file. Vài file tuỳ chọn ở gốc (app/auth.ts cho đăng nhập, app/theme.tsx cho màu và kiểu chữ) chỉ dùng để bật tính năng.
app/
├── layout.tsx → khung chung của mọi trang
├── page.tsx → trang /
└── orders/
├── page.tsx → trang /orders
├── orders.table.ts → bảng orders trong database
├── repository.ts → quy tắc nghiệp vụ của đơn hàng
├── get.ts → GET /api/orders
└── post.ts → POST /api/ordersTừ cây này, manh.run dựng ba phần:
- Giao diện: các file
page.tsx,layout.tsxthành app React dùng antd và pro-components. - API: mỗi file
get.ts,post.ts,put.ts,patch.ts,delete.tslà một endpoint Hono, dữ liệu gửi lên được kiểm bằng Zod. - Database: mỗi file
*.table.tslà một bảng Drizzle trong database SQLite riêng của app.
Giao diện gọi API qua useApiClient() trong app/api. manh.run tự sinh file này từ các handler, nên tên hàm và kiểu dữ liệu luôn khớp với API.
Đuôi file quyết định code chạy ở đâu
Hai loại file nằm cạnh nhau trong app/ nhưng chạy ở hai nơi khác nhau.
.tsxchạy trong trình duyệt: trang, layout, component. File loại này không được importapp/db,*.table.ts,hono,drizzle-ormhaymanh/env..tschạy trên server: handler, middleware, cron, bảng, repository. File loại này không được importreacthay dùngwindow,document,localStorage.
Lúc build, manh.run tách hai loại ra hai gói riêng, nên giao diện và server không import lẫn nhau được. Ngoại lệ duy nhất là app/shared/*.ts, nơi đặt kiểu, hằng số, danh sách trạng thái (defineEnum) và hàm thuần mà cả hai bên cùng dùng. Bạn chỉ viết chúng một lần.
import { z } from "@hono/zod-openapi";
import { listOrders } from "./repository"; // chỉ file .ts mới import được repository
export const schema = { query: z.object({ status: z.string().optional() }) };
export default (c, { query }) => listOrders(query); // trả object thì manh.run gửi JSONTừ code đến app chạy thật
Agent viết file, các bước còn lại do manh.run làm. Mỗi bước ứng với một tool MCP.
write_fileskhông bao giờ deploy. Bản chạy thử trong không gian làm việc đổi ngay, còn app thật thì chưa.checkchạy các bước kiểm tra nhanh trước. Mỗi lỗi trả về có tên file, số dòng và cách sửa.deploykhông chạy khicheckcòn lỗi. manh.run đưa giao diện và API lên cùng lúc, nên người dùng không gặp cảnh giao diện mới gọi API cũ. Xong mỗi lần deploy, manh.run chạy bộ kiểm thử của app (spec/acceptance.json, chưa có thì là bộ kiểm thử tự sinh) trên một bản sao có database riêng, dữ liệu thật không bị đụng tới.- Checkpoint: manh.run giữ tối đa 100 checkpoint có đặt tên, cộng với 10 bản tự lưu gần nhất (mỗi lần sửa file tự lưu một bản). Muốn quay lại bản cũ, bạn khôi phục checkpoint rồi deploy.
Cần biết
- API của app trả lỗi 503 cho tới lần deploy đầu tiên. Bản chạy thử vẫn hiện giao diện.
- Khi app chưa deploy,
<id>.manh.runhiện bản chạy thử. Deploy xong thì địa chỉ này hiện bản đã deploy. - Không tạo thư mục
app/api/. Cây thư mục phẳng theo dạngapp/<tài nguyên>/<method>.ts. app/db.ts,app/api.ts,app/hooks.tsdo manh.run tự sinh, đừng sửa tay.
Một request đi qua những đâu
Thứ tự này cố định. manh.run xác định người dùng trước, rồi chạy các middleware.ts từ thư mục cha xuống con, rồi kiểm access, cuối cùng mới tới handler. Vì quyền được kiểm trước schema, người gọi sai vai nhận 403 chứ không nhận lỗi 400 để lộ cấu trúc dữ liệu.
Bước tiếp theo
- Vì sao stack cố định — vì sao manh.run chỉ dùng antd, Hono, Drizzle và SQLite.
- Cây thư mục app/ — tra mọi loại file và URL tương ứng.
- App đầu tiên — tự làm một app từ đầu tới lúc deploy.