Stacks Route Definitions
How to define and organize routes in a Stacks application.
Key Paths
- Route files:
routes/ (api.ts, v1.ts, buddy.ts, users.ts)
- Route registry:
app/Routes.ts
Route Registry (app/Routes.ts)
Maps route files to URL prefixes:
export default {
'api': 'api', // routes/api.ts → /api/* (auto-prefixed; see #1835)
'v1': { path: 'v1', prefix: 'v1' }, // routes/v1.ts → /v1/*
'admin': { path: 'admin', prefix: 'admin', middleware: ['auth'] }
} satisfies Record<string, string | RouteDefinition>
Creating a Route File
// routes/api.ts
import { route } from '@stacksjs/router'
route.get('/users', 'Actions/ListUsers')
route.post('/users', 'Actions/CreateUser')
route.get('/users/{id}', 'Actions/ShowUser')
route.put('/users/{id}', 'Actions/UpdateUser')
route.delete('/users/{id}', 'Actions/DeleteUser')
// With inline handler
route.get('/health', (req) => Response.json({ status: 'ok' }))
// Groups
route.group({ prefix: '/admin', middleware: ['auth'] }, () => {
route.get('/dashboard', 'Actions/Dashboard')
route.get('/settings', 'Actions/Settings')
})
// Health check
route.health()
Default API Routes (routes/api.ts)
Authentication
POST /login → LoginActionPOST /register → RegisterActionPOST /auth/refresh → RefreshTokenActionGET /me → GetMeAction (auth)POST /logout → LogoutAction (auth)
Email
POST /api/email/subscribeGET /api/email/unsubscribe
AI
POST /ai/ask, POST /ai/summary
CMS & Commerce
/cms/posts/*, /cms/authors/*, /cms/categories/*, /cms/tags/*/commerce/products/*, /commerce/orders/*, /commerce/customers/*
Health
GET /health — status, uptime, memory, PID, Bun version
Versioned Routes (routes/v1.ts)
// routes/v1.ts — prefixed with /v1
route.get('/users', 'Actions/V1/ListUsers')
Handler Types
// 1. Action string (auto-loaded from app/Actions/)
route.get('/users', 'Actions/ListUsers')
// 2. Controller method
route.get('/users', 'Controllers/UserController@index')
// 3. Inline function
route.get('/ping', (req) => Response.json({ pong: true }))
CLI Commands
buddy route:list — list all registered routes
Gotchas
- Route files must be registered in
app/Routes.ts to be loaded
- String handlers (Actions/X) are dynamically imported at request time
- Route order matters — first match wins
- Use groups for shared middleware instead of repeating on each route
- The
health() helper registers GET /health automatically
- For the router API (request helpers, middleware, responses), see the
stacks-router skill
1---2name: stacks-routes-23description: Use when defining or organizing route files in a Stacks application — creating route files in routes/, registering them in app/Routes.ts, using route prefixes and middleware groups, or the default API routes structure. For the router API itself (request helpers, response helpers, middleware classes), see stacks-router.4license: MIT5---67# Stacks Route Definitions89How to define and organize routes in a Stacks application.1011## Key Paths12- Route files: `routes/` (api.ts, v1.ts, buddy.ts, users.ts)13- Route registry: `app/Routes.ts`1415## Route Registry (app/Routes.ts)1617Maps route files to URL prefixes:18```typescript19export default {20 'api': 'api', // routes/api.ts → /api/* (auto-prefixed; see #1835)21 'v1': { path: 'v1', prefix: 'v1' }, // routes/v1.ts → /v1/*22 'admin': { path: 'admin', prefix: 'admin', middleware: ['auth'] }23} satisfies Record<string, string | RouteDefinition>24```2526## Creating a Route File2728```typescript29// routes/api.ts30import { route } from '@stacksjs/router'3132route.get('/users', 'Actions/ListUsers')33route.post('/users', 'Actions/CreateUser')34route.get('/users/{id}', 'Actions/ShowUser')35route.put('/users/{id}', 'Actions/UpdateUser')36route.delete('/users/{id}', 'Actions/DeleteUser')3738// With inline handler39route.get('/health', (req) => Response.json({ status: 'ok' }))4041// Groups42route.group({ prefix: '/admin', middleware: ['auth'] }, () => {43 route.get('/dashboard', 'Actions/Dashboard')44 route.get('/settings', 'Actions/Settings')45})4647// Health check48route.health()49```5051## Default API Routes (routes/api.ts)5253### Authentication54- `POST /login` → LoginAction55- `POST /register` → RegisterAction56- `POST /auth/refresh` → RefreshTokenAction57- `GET /me` → GetMeAction (auth)58- `POST /logout` → LogoutAction (auth)5960### Email61- `POST /api/email/subscribe`62- `GET /api/email/unsubscribe`6364### AI65- `POST /ai/ask`, `POST /ai/summary`6667### CMS & Commerce68- `/cms/posts/*`, `/cms/authors/*`, `/cms/categories/*`, `/cms/tags/*`69- `/commerce/products/*`, `/commerce/orders/*`, `/commerce/customers/*`7071### Health72- `GET /health` — status, uptime, memory, PID, Bun version7374## Versioned Routes (routes/v1.ts)7576```typescript77// routes/v1.ts — prefixed with /v178route.get('/users', 'Actions/V1/ListUsers')79```8081## Handler Types8283```typescript84// 1. Action string (auto-loaded from app/Actions/)85route.get('/users', 'Actions/ListUsers')8687// 2. Controller method88route.get('/users', 'Controllers/UserController@index')8990// 3. Inline function91route.get('/ping', (req) => Response.json({ pong: true }))92```9394## CLI Commands95- `buddy route:list` — list all registered routes9697## Gotchas98- Route files must be registered in `app/Routes.ts` to be loaded99- String handlers (Actions/X) are dynamically imported at request time100- Route order matters — first match wins101- Use groups for shared middleware instead of repeating on each route102- The `health()` helper registers `GET /health` automatically103- For the router API (request helpers, middleware, responses), see the `stacks-router` skill
stacksjs