also looking at this
Deploy: uniform auth session model (main → production)
#7
282 files
+3028
-64856
| @@ -1,303 +0,0 @@ | ||
| 1 | --- | |
| 2 | title: Routing | |
| 3 | --- | |
| 4 | // Points to app/Controllers/ComingSoonController.ts, index method | |
| 5 | route.get('/coming-soon', 'Controllers/ComingSoonController@index') | |
| 6 | ||
| 7 | // Points to app/Controllers/QueryController.ts with various methods | |
| 8 | route.get('/queries/stats', 'Controllers/QueryController@getStats') | |
| 9 | route.get('/queries/recent', 'Controllers/QueryController@getRecentQueries') | |
| 10 | route.get('/queries/slow', 'Controllers/QueryController@getSlowQueries') | |
| 11 | route.get('/queries/:id', 'Controllers/QueryController@getQuery') | |
| 12 | route.post('/queries/prune', 'Controllers/QueryController@pruneQueryLogs') | |
| 13 | ||
| 14 | ``` | |
| 15 | ||
| 16 | ### Action File Structure | |
| 17 | ||
| 18 | When you reference `'Actions/Auth/LoginAction'`, Stacks looks for this file: | |
| 19 | ||
| 20 | ```typescript | |
| 21 | ||
| 22 | // app/Actions/Auth/LoginAction.ts | |
| 23 | import type { RequestInstance } from '@stacksjs/types' | |
| 24 | import { Action } from '@stacksjs/actions' | |
| 25 | import { Auth } from '@stacksjs/auth' | |
| 26 | import { response } from '@stacksjs/router' | |
| 27 | import { schema } from '@stacksjs/validation' | |
| 28 | ||
| 29 | export default new Action({ | |
| 30 | name: 'LoginAction', | |
| 31 | description: 'Login to the application', | |
| 32 | method: 'POST', | |
| 33 | ||
| 34 | validations: { | |
| 35 | email: { | |
| 36 | rule: schema.string().email(), | |
| 37 | message: 'Email must be a valid email address.', | |
| 38 | }, | |
| 39 | password: { | |
| 40 | rule: schema.string().min(6).max(255), | |
| 41 | message: 'Password must be between 6 and 255 characters.', | |
| 42 | }, | |
| 43 | }, | |
| 44 | ||
| 45 | async handle(request: RequestInstance) { | |
| 46 | const email = request.get('email') | |
| 47 | const password = request.get('password') | |
| 48 | ||
| 49 | const result = await Auth.login({ email, password }) | |
| 50 | ||
| 51 | if (result) { | |
| 52 | return response.json({ | |
| 53 | token: result.token, | |
| 54 | user: { | |
| 55 | id: result.user?.id, | |
| 56 | email: result.user?.email, | |
| 57 | name: result.user?.name, | |
| 58 | }, | |
| 59 | }) | |
| 60 | } | |
| 61 | ||
| 62 | return response.unauthorized('Incorrect email or password') | |
| 63 | }, | |
| 64 | }) | |
| 65 | ||
| 66 | ``` | |
| 67 | ||
| 68 | ## Route Groups | |
| 69 | ||
| 70 | Group related routes with shared configuration: | |
| 71 | ||
| 72 | ### Prefix Groups | |
| 73 | ||
| 74 | ```typescript | |
| 75 | ||
| 76 | // All routes in this group will be prefixed with /auth | |
| 77 | route.group({ prefix: '/auth' }, () => { | |
| 78 | route.post('/refresh', 'Actions/Auth/RefreshTokenAction') | |
| 79 | route.get('/tokens', 'Actions/Auth/ListTokensAction') | |
| 80 | route.post('/token', 'Actions/Auth/CreateTokenAction') | |
| 81 | route.delete('/tokens/{id}', 'Actions/Auth/RevokeTokenAction') | |
| 82 | }) | |
| 83 | ||
| 84 | // Nested prefix groups | |
| 85 | route.group({ prefix: '/api/v1' }, () => { | |
| 86 | route.group({ prefix: '/users' }, () => { | |
| 87 | route.get('/', 'Actions/User/IndexAction') | |
| 88 | route.get('/{id}', 'Actions/User/ShowAction') | |
| 89 | route.post('/', 'Actions/User/StoreAction') | |
| 90 | }) | |
| 91 | }) | |
| 92 | ||
| 93 | ``` | |
| 94 | ||
| 95 | ### Middleware Groups | |
| 96 | ||
| 97 | ```typescript | |
| 98 | ||
| 99 | // Apply middleware to all routes in the group | |
| 100 | route.group({ middleware: 'auth' }, () => { | |
| 101 | route.get('/me', 'Actions/Auth/AuthUserAction') | |
| 102 | route.post('/logout', 'Actions/Auth/LogoutAction') | |
| 103 | }) | |
| 104 | ||
| 105 | // Multiple middleware | |
| 106 | route.group({ middleware: ['auth', 'throttle:60,1'] }, () => { | |
| 107 | route.get('/dashboard', 'Actions/DashboardAction') | |
| 108 | route.get('/settings', 'Actions/SettingsAction') | |
| 109 | }) | |
| 110 | ||
| 111 | ``` | |
| 112 | ||
| 113 | ### Combined Group Options | |
| 114 | ||
| 115 | ```typescript | |
| 116 | ||
| 117 | route.group({ prefix: '/payments', middleware: 'auth' }, () => { | |
| 118 | route.get('/fetch-customer/{id}', 'Actions/Payment/FetchPaymentCustomerAction') | |
| 119 | route.get('/transaction-history/{id}', 'Actions/Payment/FetchTransactionHistoryAction') | |
| 120 | route.post('/create-subscription/{id}', 'Actions/Payment/CreateSubscriptionAction') | |
| 121 | route.post('/cancel-subscription/{id}', 'Actions/Payment/CancelSubscriptionAction') | |
| 122 | }) | |
| 123 | ||
| 124 | ``` | |
| 125 | ||
| 126 | ## Middleware Attachment | |
| 127 | ||
| 128 | ### Single Route Middleware | |
| 129 | ||
| 130 | ```typescript | |
| 131 | ||
| 132 | // Chain middleware to individual routes | |
| 133 | route.get('/admin', 'Actions/AdminAction').middleware('auth') | |
| 134 | ||
| 135 | // Multiple middleware on a single route | |
| 136 | route.get('/admin/settings', 'Actions/AdminSettingsAction') | |
| 137 | .middleware('auth') | |
| 138 | .middleware('abilities:admin') | |
| 139 | ||
| 140 | // Middleware with parameters | |
| 141 | route.post('/api/data', 'Actions/DataAction') | |
| 142 | .middleware('throttle:100,1') | |
| 143 | .middleware('auth') | |
| 144 | ||
| 145 | ``` | |
| 146 | ||
| 147 | ### Available Middleware | |
| 148 | ||
| 149 | Stacks comes with several built-in middleware defined in `app/Middleware.ts`: | |
| 150 | ||
| 151 | ```typescript | |
| 152 | ||
| 153 | export default { | |
| 154 | 'maintenance': 'Maintenance', | |
| 155 | 'auth': 'Auth', | |
| 156 | 'guest': 'Guest', | |
| 157 | 'api': 'Api', | |
| 158 | 'team': 'Team', | |
| 159 | 'logger': 'Logger', | |
| 160 | 'abilities': 'Abilities', | |
| 161 | 'can': 'Can', | |
| 162 | 'throttle': 'Throttle', | |
| 163 | 'env': 'Env', | |
| 164 | 'env:local': 'EnvLocal', | |
| 165 | 'env:development': 'EnvDevelopment', | |
| 166 | 'env:staging': 'EnvStaging', | |
| 167 | 'env:production': 'EnvProduction', | |
| 168 | } satisfies Middleware | |
| 169 | ||
| 170 | ``` | |
| 171 | ||
| 172 | For more details, see the [Middleware documentation](/basics/middleware). | |
| 173 | ||
| 174 | ## Route File Registry | |
| 175 | ||
| 176 | Stacks uses `app/Routes.ts` to register which route files to load and how to prefix them: | |
| 177 | ||
| 178 | ```typescript | |
| 179 | ||
| 180 | // app/Routes.ts | |
| 181 | export default { | |
| 182 | // Default API routes - loads routes/api.ts at /api/* | |
| 183 | // (The 'api' key auto-prefixes with /api so user routes line up | |
| 184 | // with the rpx proxy forward path. See stacksjs/stacks#1835.) | |
| 185 | 'api': 'api', | |
| 186 | ||
| 187 | // Versioned routes with explicit prefix - loads routes/v1.ts at /v1/* | |
| 188 | 'v1': { path: 'v1', prefix: 'v1' }, | |
| 189 | ||
| 190 | // Admin routes with middleware - loads routes/admin.ts at /admin/* | |
| 191 | 'admin': { path: 'admin', middleware: ['auth'] }, | |
| 192 | ||
| 193 | // No prefix override - loads routes/internal.ts at /* (no prefix) | |
| 194 | // 'web' is the only key in the route-loader's NO*PREFIX*KEYS list; | |
| 195 | // for other no-prefix routes, pass an explicit empty string. | |
| 196 | 'internal': { path: 'internal', prefix: '' }, | |
| 197 | } satisfies RouteRegistry | |
| 198 | ||
| 199 | ``` | |
| 200 | ||
| 201 | ### Route Definition Types | |
| 202 | ||
| 203 | ```typescript | |
| 204 | ||
| 205 | export interface RouteDefinition { | |
| 206 | /** Route file path (relative to routes/) */ | |
| 207 | path: string | |
| 208 | /** Optional URL prefix (overrides the key-based prefix) */ | |
| 209 | prefix?: string | |
| 210 | /** Optional middleware for all routes in file */ | |
| 211 | middleware?: string | string[] | |
| 212 | } | |
| 213 | ||
| 214 | // Simple string format (key becomes prefix) | |
| 215 | 'v1': 'api/v1', // Loads routes/api/v1.ts at /v1/* | |
| 216 | ||
| 217 | // Object format with explicit config | |
| 218 | 'legacy': { path: 'api/v1', prefix: '/api/v1' }, | |
| 219 | ||
| 220 | ``` | |
| 221 | ||
| 222 | ## Special Routes | |
| 223 | ||
| 224 | ### Health Check Route | |
| 225 | ||
| 226 | Stacks provides a built-in health check route: | |
| 227 | ||
| 228 | ```typescript | |
| 229 | ||
| 230 | // Adds GET /health endpoint | |
| 231 | route.health() | |
| 232 | ||
| 233 | ``` | |
| 234 | ||
| 235 | This returns a JSON response with service status information. | |
| 236 | ||
| 237 | ### Email Route | |
| 238 | ||
| 239 | ```typescript | |
| 240 | ||
| 241 | // Adds email preview route (development only) | |
| 242 | route.email('/welcome') | |
| 243 | ||
| 244 | ``` | |
| 245 | ||
| 246 | ## Edge Cases and Advanced Patterns | |
| 247 | ||
| 248 | ### Optional Parameters | |
| 249 | ||
| 250 | Currently, Stacks handles optional parameters through separate route definitions: | |
| 251 | ||
| 252 | ```typescript | |
| 253 | ||
| 254 | // Two routes for optional parameter | |
| 255 | route.get('/posts', 'Actions/Post/IndexAction') | |
| 256 | route.get('/posts/{category}', 'Actions/Post/IndexAction') | |
| 257 | ||
| 258 | ``` | |
| 259 | ||
| 260 | ### Catch-All Routes | |
| 261 | ||
| 262 | ```typescript | |
| 263 | ||
| 264 | // Match any path under /docs | |
| 265 | route.get('/docs/{path}', 'Actions/DocsAction').where('path', '.*') | |
| 266 | ||
| 267 | ``` | |
| 268 | ||
| 269 | ### Route Priority | |
| 270 | ||
| 271 | Routes are matched in the order they are defined. More specific routes should come before catch-all routes: | |
| 272 | ||
| 273 | ```typescript | |
| 274 | ||
| 275 | // Specific route first | |
| 276 | route.get('/users/me', 'Actions/User/CurrentUserAction') | |
| 277 | ||
| 278 | // Parameterized route after | |
| 279 | route.get('/users/{id}', 'Actions/User/ShowAction') | |
| 280 | ||
| 281 | // Catch-all route last | |
| 282 | route.get('/users/{path}', 'Actions/User/FallbackAction').where('path', '.*') | |
| 283 | ||
| 284 | ``` | |
| 285 | ||
| 286 | ### Route Naming (Coming Soon) | |
| 287 | ||
| 288 | ```typescript | |
| 289 | ||
| 290 | // Future support for named routes | |
| 291 | route.get('/users/{id}', 'Actions/User/ShowAction').name('users.show') | |
| 292 | ||
| 293 | // Generate URL from route name | |
| 294 | const url = route.url('users.show', { id: 123 }) | |
| 295 | ||
| 296 | ``` | |
| 297 | ||
| 298 | ## Related Documentation | |
| 299 | ||
| 300 | - [Middleware](/basics/middleware) - Learn about request middleware | |
| 301 | - [Actions](/basics/actions) - Creating action handlers | |
| 302 | - [Controllers](/basics/controllers) - Using controllers | |
| 303 | - [Validation](/packages/validation) - Request validation | |