Skip to Content

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/orders

Từ cây này, manh.run dựng ba phần:

  • Giao diện: các file page.tsx, layout.tsx thành app React dùng antd và pro-components.
  • API: mỗi file get.ts, post.ts, put.ts, patch.ts, delete.ts là một endpoint Hono, dữ liệu gửi lên được kiểm bằng Zod.
  • Database: mỗi file *.table.ts là 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.

  • .tsx chạy trong trình duyệt: trang, layout, component. File loại này không được import app/db, *.table.ts, hono, drizzle-orm hay manh/env.
  • .ts chạy trên server: handler, middleware, cron, bảng, repository. File loại này không được import react hay dùng window, 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.

app/orders/get.ts
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 JSON

Từ 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_files khô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.
  • check chạ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.
  • deploy không chạy khi check cò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.run hiệ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ạng app/<tài nguyên>/<method>.ts.
  • app/db.ts, app/api.ts, app/hooks.ts do 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

Cập nhật