Skip to Content

The app/ directory

All of an app’s code lives in app/. For example app/orders/page.tsx is the page /orders, and app/orders/post.ts is the API POST /api/orders.

There is no route configuration. Each folder is a URL segment, and the file name tells manh.run what to do with the file.

Tree

app/ ├── layout.tsx # root layout, wraps every page ├── page.tsx # page / ├── theme.tsx # APP_THEME: color, radius, dark mode ├── auth.ts # (optional) turns on sign-in: roles, sign-up, Google ├── upstream.ts # (optional) forward to an existing API ├── middleware.ts # runs before every handler ├── db.ts api.ts hooks.ts # [generated] not stored in the project ├── components/ # components used on 2+ pages (StatusTag.tsx) ├── shared/ # what both pages and the server need ├── lib/ # helpers for one side ├── support/ │ └── bot.telegram.ts # messages sent to the app's Telegram bot └── orders/ ├── orders.table.ts # the orders table ├── repository.ts # database calls + business rules ├── orders-columns.tsx # columns shared by table, form, detail ├── page.tsx # page /orders ├── get.ts post.ts # GET, POST /api/orders ├── daily-digest.cron.ts # scheduled job ├── send-invoice.job.ts # background job ├── orders.email.ts # receives mail sent to the app └── [id:int]/ ├── page.tsx # page /orders/:id └── get.ts patch.ts # GET, PATCH /api/orders/:id

The page shows at https://<id>.manh.run/orders; the handler answers at https://<id>.manh.run/api/orders.

Two runtimes: .tsx and .ts

The extension decides where the code runs. Two files in the same folder are still built separately.

ExtensionRuns inExamplesMust not import
.tsxBrowserpage.tsx, layout.tsx, *-columns.tsx, components/*.tsxapp/db, *.table.ts, hono, drizzle-orm, manh/env
.tsServerhandlers, middleware.ts, *.cron.ts, *.job.ts, *.table.ts, repository.ts, lib/*.tsreact, react-dom, react-router
  • Pages reach the server over HTTP with useApiClient() from app/api, never by calling a server function.
  • Only app/shared/*.ts is imported by both sides. Files there import only app/shared/*, manh/enum, manh/flow, manh/vn and contain no JSX. See shared/.
  • .ts files have no window, document or localStorage.

Naming

PartConventionExample
Folderkebab-caseapp/order-items/
Convention filelowercasepage.tsx, get.ts, orders.table.ts
ComponentPascalCase, same as the componentapp/components/StatusTag.tsx
Dynamic segment[name:type]app/orders/[id:int]/
Route group(group), not in the URLapp/(admin)/users/

In a route folder, don’t name files after verbs like list.ts or create.ts: only method names (get.ts, post.ts) become handlers. Under app/lib/ any name works.

Typed dynamic segments

The type goes after the :. manh.run builds the parameter check for handlers and pages from the path itself, so you never declare the parameter in schema.

SyntaxValid values
[id:int]integer ([id:number] works too)
[id:uuid]UUID
[slug:slug]lowercase letters, digits, -
[id]any string, not checked
  • The type is not part of the URL: app/orders/[id:int]/get.ts answers /api/orders/:id.
  • There is no email, date, boolean or url type. Send those values in the query or body.
  • A bad value shows a 404 page, or a 400 from a handler.
  • Static beats dynamic: app/orders/stats/get.ts never falls into [id:int]/get.ts.

Every file kind

Good to know

  • Import through the app/ prefix (app/db, app/api). Never use a relative path that leaves app/.
  • (group)/page.tsx is invalid: the group is not in the URL, so this page has the same URL as the parent folder’s page.tsx.
  • A [param]/ folder needs a page.tsx or a method file. Empty dynamic folders are ignored.
  • One file, one job: get.ts handles GET only and never branches on c.req.method.
  • Each app has exactly one database. To keep each client company’s data fully apart, give each client their own project with the same code.

Next steps

Last updated