Introduction
Elegant decorator-based routing for AdonisJS v7
Girouette
Elegant decorator-based routing for AdonisJS v7
Girouette provides a beautiful, fluent API for defining your AdonisJS routes using decorators. By bringing route definitions closer to your controller methods, Girouette makes your application's routing more intuitive and maintainable.
Why Girouette?
Traditional AdonisJS routing requires defining routes in a separate file, which can become difficult to maintain as your application grows. Girouette solves this by:
- Colocation: Keep route definitions next to your controller methods
- Type Safety: Full TypeScript support with decorator metadata
- Familiar Patterns: Similar to routing in NestJS, Laravel, or Spring Boot
- Zero Runtime Overhead: Routes are registered at boot time
- Tuyau Compatible: Works seamlessly with AdonisJS's type-safe API client
Quick Example
import { Get, Post, Middleware } from '@adonisjs-community/girouette'
import { middleware } from '#start/kernel'
import { HttpContext } from '@adonisjs/core/http'
export default class UsersController {
@Get('/users')
async index() {
return User.all()
}
@Get('/users/:id')
async show({ params }: HttpContext) {
return User.findOrFail(params.id)
}
@Post('/users')
@Middleware([middleware.auth()])
async store({ request }: HttpContext) {
return User.create(request.body())
}
}How It Works
Girouette generates a start/routes.girouette.ts file that contains all your decorated routes. This file is automatically kept in sync with your controllers, enabling Hot Module Replacement (HMR) during development. When you modify the logic inside a controller method, your changes are reflected instantly without restarting the server.
When you change the routing itself (adding/removing routes, modifying paths, or changing decorators), a full server reload is required since routes are registered at boot time.
Girouette automatically scans your controllers and registers routes at application boot. No additional configuration needed after installation.
Features at a Glance
HTTP Methods
@Get, @Post, @Put, @Patch, @Delete, @Any decorators for all HTTP methods
Route Groups
Group routes with shared prefixes, middleware, and domain restrictions
RESTful Resources
Automatic CRUD route generation with @Resource decorator
Middleware
Apply middleware at route, resource, or group level
Route Constraints
Validate route parameters with regex or custom matchers
HMR Support
Instant updates to route logic during development without server restarts
Getting Started
Install Girouette via the AdonisJS CLI:
node ace add @adonisjs-community/girouetteThat's it! You can now start using decorators in your controllers.
Available Decorators
| Decorator | Description |
|---|---|
@Get | Define a GET route |
@Post | Define a POST route |
@Put | Define a PUT route |
@Patch | Define a PATCH route |
@Delete | Define a DELETE route |
@Any | Match any HTTP method |
@Resource | Create RESTful resource routes |
@Group | Group routes with prefix/name |
@GroupMiddleware | Apply middleware to all routes |
@GroupDomain | Restrict routes to a domain |
@Middleware | Apply middleware to a route |
@ResourceMiddleware | Apply middleware to resource actions |
@Where | Add route parameter constraints |
@Pick | Include specific resource actions |
@Except | Exclude specific resource actions |
@ApiOnly | Include only API actions |
Next Steps
- Installation Guide - Detailed setup instructions
- Basic Routing - Learn the HTTP method decorators
- Resources - RESTful resource controllers