Thư mục app/
Mọi code của app nằm trong app/. Ví dụ app/orders/page.tsx là trang /orders, còn app/orders/post.ts là API POST /api/orders.
Không có file khai báo route. Mỗi thư mục là một đoạn URL, tên file cho manh.run biết phải làm gì với file đó.
Cây thư mục
app/
├── layout.tsx # layout gốc, bọc mọi trang
├── page.tsx # trang /
├── theme.tsx # APP_THEME: màu, bo góc, dark mode
├── auth.ts # (tuỳ chọn) bật đăng nhập: vai trò, cách đăng ký, Google
├── upstream.ts # (tuỳ chọn) chuyển tiếp tới API có sẵn
├── middleware.ts # chạy trước mọi handler
├── db.ts api.ts hooks.ts # [sinh sẵn] không nằm trong project
├── components/ # component dùng ở 2+ trang (StatusTag.tsx)
├── shared/ # phần cả trang lẫn server cần
├── lib/ # hàm phụ của từng phía
├── support/
│ └── bot.telegram.ts # tin nhắn gửi tới bot Telegram của app
└── orders/
├── orders.table.ts # bảng orders
├── repository.ts # lệnh database + quy tắc nghiệp vụ
├── orders-columns.tsx # cột dùng chung cho bảng, form, chi tiết
├── page.tsx # trang /orders
├── get.ts post.ts # GET, POST /api/orders
├── daily-digest.cron.ts # job theo lịch
├── send-invoice.job.ts # việc chạy nền
├── orders.email.ts # nhận email gửi tới app
└── [id:int]/
├── page.tsx # trang /orders/:id
└── get.ts patch.ts # GET, PATCH /api/orders/:idTrang hiện ở https://<id>.manh.run/orders, handler trả lời ở https://<id>.manh.run/api/orders.
Hai runtime: .tsx và .ts
Đuôi file quyết định code chạy ở đâu. Hai file nằm cùng thư mục vẫn được tách riêng khi build.
| Đuôi | Chạy ở | Ví dụ | Không được import |
|---|---|---|---|
.tsx | Trình duyệt | page.tsx, layout.tsx, *-columns.tsx, components/*.tsx | app/db, *.table.ts, hono, drizzle-orm, manh/env |
.ts | Server | handler, middleware.ts, *.cron.ts, *.job.ts, *.table.ts, repository.ts, lib/*.ts | react, react-dom, react-router |
- Trang gọi server qua HTTP bằng
useApiClient()từapp/api, không gọi thẳng hàm của server. - Chỉ
app/shared/*.tsđược cả hai phía import. File ở đó chỉ importapp/shared/*,manh/enum,manh/flow,manh/vnvà không chứa JSX. Xem shared/. - File
.tskhông cówindow,document,localStorage.
Đặt tên
| Thành phần | Quy ước | Ví dụ |
|---|---|---|
| Thư mục | kebab-case | app/order-items/ |
| File quy ước | chữ thường | page.tsx, get.ts, orders.table.ts |
| Component | PascalCase, trùng tên component | app/components/StatusTag.tsx |
| Segment động | [name:type] | app/orders/[id:int]/ |
| Nhóm route | (group), không có trong URL | app/(admin)/users/ |
Trong thư mục route, đừng đặt tên file theo động từ như list.ts hay create.ts: chỉ file mang tên method (get.ts, post.ts) mới thành handler. Trong app/lib/ đặt tên gì cũng được.
Segment động có kiểu
Kiểu viết sau dấu :. manh.run dựa vào đường dẫn để tạo phần kiểm tham số cho cả handler và trang, nên bạn không khai báo tham số trong schema.
| Cú pháp | Giá trị hợp lệ |
|---|---|
[id:int] | số nguyên ([id:number] cũng được) |
[id:uuid] | UUID |
[slug:slug] | chữ thường, số, - |
[id] | chuỗi bất kỳ, không kiểm |
- Kiểu không có trong URL:
app/orders/[id:int]/get.tstrả lời/api/orders/:id. - Không có kiểu
email,date,boolean,url. Các giá trị đó đi qua query hoặc body. - Giá trị sai thì trang hiện 404, handler trả 400.
- Đoạn tĩnh được ưu tiên hơn đoạn động:
app/orders/stats/get.tskhông bao giờ rơi vào[id:int]/get.ts.
Từng loại file
- Giao diện: page.tsx · layout.tsx ·
<resource>-columns.tsx· components/ · theme.tsx - Server: get.ts, post.ts… · middleware.ts ·
<resource>.table.ts· repository.ts - Việc không qua request: *.cron.ts · *.job.ts · *.email.ts · *.telegram.ts
- Dùng chung và hàm phụ: shared/ · lib/
- Cấu hình ở gốc: auth.ts · upstream.ts
- Do manh.run sinh: db.ts, api.ts, hooks.ts
Cần biết
- Import qua tiền tố
app/(app/db,app/api). Không dùng đường dẫn tương đối đi ra ngoàiapp/. (group)/page.tsxkhông hợp lệ: nhóm không có trong URL nên trang này trùng URL vớipage.tsxcủa thư mục cha.- Thư mục
[param]/phải cópage.tsxhoặc một file method. Thư mục động rỗng bị bỏ qua. - Mỗi file làm một việc:
get.tschỉ xử lý GET, không rẽ nhánh theoc.req.method. - Mỗi app dùng đúng một database. Cần tách hẳn dữ liệu của từng công ty khách thì tạo cho mỗi khách một project, cùng code.
Bước tiếp theo
- page.tsx — trang đầu tiên của app hiện ra từ file này.
- get.ts, post.ts… — viết API mà trang gọi tới.
- Trang và layout — URL của trang, layout lồng nhau và nhóm route.
Cập nhật