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/:idThe 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.
| Extension | Runs in | Examples | Must not import |
|---|---|---|---|
.tsx | Browser | page.tsx, layout.tsx, *-columns.tsx, components/*.tsx | app/db, *.table.ts, hono, drizzle-orm, manh/env |
.ts | Server | handlers, middleware.ts, *.cron.ts, *.job.ts, *.table.ts, repository.ts, lib/*.ts | react, react-dom, react-router |
- Pages reach the server over HTTP with
useApiClient()fromapp/api, never by calling a server function. - Only
app/shared/*.tsis imported by both sides. Files there import onlyapp/shared/*,manh/enum,manh/flow,manh/vnand contain no JSX. See shared/. .tsfiles have nowindow,documentorlocalStorage.
Naming
| Part | Convention | Example |
|---|---|---|
| Folder | kebab-case | app/order-items/ |
| Convention file | lowercase | page.tsx, get.ts, orders.table.ts |
| Component | PascalCase, same as the component | app/components/StatusTag.tsx |
| Dynamic segment | [name:type] | app/orders/[id:int]/ |
| Route group | (group), not in the URL | app/(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.
| Syntax | Valid 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.tsanswers/api/orders/:id. - There is no
email,date,booleanorurltype. 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.tsnever falls into[id:int]/get.ts.
Every file kind
- UI: page.tsx · layout.tsx ·
<resource>-columns.tsx· components/ · theme.tsx - Server: get.ts, post.ts… · middleware.ts ·
<resource>.table.ts· repository.ts - Work outside a request: *.cron.ts · *.job.ts · *.email.ts · *.telegram.ts
- Shared code and helpers: shared/ · lib/
- Root configuration: auth.ts · upstream.ts
- Generated by manh.run: db.ts, api.ts, hooks.ts
Good to know
- Import through the
app/prefix (app/db,app/api). Never use a relative path that leavesapp/. (group)/page.tsxis invalid: the group is not in the URL, so this page has the same URL as the parent folder’spage.tsx.- A
[param]/folder needs apage.tsxor a method file. Empty dynamic folders are ignored. - One file, one job:
get.tshandles GET only and never branches onc.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
- page.tsx — the app’s first page comes from this file.
- get.ts, post.ts… — write the API your pages call.
- Pages and layouts — page URLs, nested layouts and route groups.