Skip to Content

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/:id

Trang 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ôiChạy ởVí dụKhông được import
.tsxTrình duyệtpage.tsx, layout.tsx, *-columns.tsx, components/*.tsxapp/db, *.table.ts, hono, drizzle-orm, manh/env
.tsServerhandler, middleware.ts, *.cron.ts, *.job.ts, *.table.ts, repository.ts, lib/*.tsreact, 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ỉ import app/shared/*, manh/enum, manh/flow, manh/vn và không chứa JSX. Xem shared/.
  • File .ts không có window, document, localStorage.

Đặt tên

Thành phầnQuy ướcVí dụ
Thư mụckebab-caseapp/order-items/
File quy ướcchữ thườngpage.tsx, get.ts, orders.table.ts
ComponentPascalCase, trùng tên componentapp/components/StatusTag.tsx
Segment động[name:type]app/orders/[id:int]/
Nhóm route(group), không có trong URLapp/(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ápGiá 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.ts trả 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.ts không bao giờ rơi vào [id:int]/get.ts.

Từng loại file

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ài app/.
  • (group)/page.tsx không hợp lệ: nhóm không có trong URL nên trang này trùng URL với page.tsx của thư mục cha.
  • Thư mục [param]/ phải có page.tsx hoặc một file method. Thư mục động rỗng bị bỏ qua.
  • Mỗi file làm một việc: get.ts chỉ xử lý GET, không rẽ nhánh theo c.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

Cập nhật