Use when working with routing in a Stacks application — defining routes, HTTP methods, route groups, middleware, named routes, URL generation, request enhancement (Laravel-style input/query/file helpers), response helpers, error responses, route model binding, or rate limiting. Covers @stacksjs/router, routes/, and app/Routes.ts.
Built on @stacksjs/bun-router with ts-rate-limiter.
storage/framework/core/router/src/routes/ (api.ts, v1.ts, buddy.ts, users.ts)app/Routes.tsstorage/framework/types/router.d.tsstorage/framework/types/dashboard-router.d.tsimport { route } from '@stacksjs/router'
route.get('/users', handler)
route.post('/users', handler)
route.put('/users/{id}', handler)
route.patch('/users/{id}', handler)
route.delete('/users/{id}', handler)
route.options('/users', handler)
route.health() // GET /health endpoint
route.get('/admin', handler)
.middleware('auth')
.name('admin.dashboard')
route.group({ prefix: '/api/v1', middleware: ['auth', 'throttle'] }, () => {
route.get('/users', listUsers)
route.post('/users', createUser)
})
(req: EnhancedRequest) => Response | Promise<Response>'Actions/CreateUser' — auto-loads action'Controllers/UserController@index' — calls controller methodexport default {
'api': 'api', // routes/api.ts → / (no prefix)
'v1': { path: 'v1', prefix: 'v1' }, // routes/v1.ts → /v1/*
'admin': { path: 'admin', prefix: 'admin', middleware: ['auth'] }
} satisfies Record<string, string | RouteDefinition>
req.get('name', 'default') // get input value
req.input('name', 'default') // alias
req.all() // all input
req.only(['name', 'email']) // specific fields
req.except(['password']) // all except
req.has('name') // exists?
req.has(['name', 'email']) // all exist?
req.hasAny(['name', 'email']) // any exist?
req.filled('name') // exists and not empty?
req.missing('name') // doesn't exist?
req.query // query parameters object
req.string('name', '')
req.integer('page', 1)
req.float('price', 0.0)
req.boolean('active', false)
req.array('tags')
const file = req.file('avatar') // UploadedFile | null
const files = req.getFiles('images') // UploadedFile[]
req.hasFile('avatar') // boolean
const all = req.allFiles() // Record<string, UploadedFile[]>
const user = await req.user()
const token = await req.userToken()
await req.tokenCan('create-posts')
await req.tokenCant('delete-users')
import { response } from '@stacksjs/router'
response.json(data, { status: 200 })
response.created(data) // 201
response.noContent() // 204
response.badRequest(data) // 400
response.unauthorized() // 401
response.forbidden() // 403
response.notFound() // 404
response.error() // 500
response.redirect(url, 302)
response.text('hello')
response.html('<h1>Hi</h1>')
createErrorResponse(error, request, options?)
createMiddlewareErrorResponse(error, request)
createValidationErrorResponse(errors, request)
createNotFoundResponse(path, request)
Error response body:
{ error: string, message: string, status: number, timestamp: string, details?: Record<string, unknown> }
import { getCurrentRequest, setCurrentRequest, runWithRequest, request } from '@stacksjs/router'
// Async context management
const req = getCurrentRequest()
runWithRequest(req, async () => {
// `request` proxy available here
})
import { Middleware } from '@stacksjs/router'
const logger = new Middleware({
name: 'logger',
priority: 5, // lower = runs first, default 10
handle: async (request: EnhancedRequest) => {
console.log(`${request.method} ${request.url}`)
}
})
route.use(logger)
maintenance, auth, guest, api, team, logger, abilities, can, throttle, local, development, staging, production, env.local, env.development, env.staging, env.production, role, permission, verified
trackQuery(query, time?, connection?)
clearTrackedQueries()
clearMiddlewareCache()
POST /login, POST /register, POST /auth/refresh, POST /auth/tokenGET /auth/tokens, DELETE /auth/tokens/{id} (auth)GET /me, POST /logout (auth)POST /api/email/subscribe, GET /api/email/unsubscribePOST /ai/ask, POST /ai/summary/cms/posts/*, /cms/authors/*, /cms/categories/*, /cms/tags/*, /cms/comments/*/commerce/products/*, /commerce/orders/*, /commerce/customers/*, /shipping/*/monitoring/errors/*GET /health — returns status, uptime, memory, PID, Bun versionimport { serve, serverResponse } from '@stacksjs/router'
await serve({ port: 3000 })
const response = await serverResponse(request)
import { url } from '@stacksjs/router'
url('admin.dashboard') // '/admin/dashboard'
url('user.show', { id: 42 }) // '/users/42'
@stacksjs/bun-router under the hoodts-rate-limiter is built into the routerapp/Routes.ts maps file names to URL prefixes'Actions/MyAction') are dynamically importedrequest proxy uses AsyncLocalStorage for context — must be inside runWithRequest()UploadedFile objects with metadataclearTrackedQueries() to free memorystorage/framework/types/router.d.ts