Menu
Use when working with AdonisJS v7, including migration guidance for v6 projects
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
| name | adonisjs |
| description | Use when working with AdonisJS v7, including migration guidance for v6 projects |
| doc_version | adonisjs |
Use when working with AdonisJS v7, a modern TypeScript backend framework. This skill combines knowledge from the official documentation to provide comprehensive guidance for building server-side applications.
This skill should be triggered when working with:
references/other.md and follow the "Upgrade guide - AdonisJS" (https://docs.adonisjs.com/v6-to-v7)AdonisJS is deeply opinionated about the backend but flexible about the frontend:
Hypermedia (Server-Rendered): Edge templates + Alpine.js/HTMX
Inertia (React/Vue): React/Vue as views + server routing
API-Only: JSON backend + separate frontend
| Component | Purpose | Location |
|---|---|---|
| Routes | Define URL endpoints | routes/*.ts |
| Controllers | Handle HTTP requests | app/controllers/*.ts |
| Middleware | Process requests/responses | app/middleware/*.ts |
| Models | Database entities (Lucid) | app/models/*.ts |
| Services | Business logic | app/services/*.ts |
| Migrations | Database schema | database/migrations/*.ts |
| Validators | Request validation | app/validators/*.ts |
public vs resources directories:
public/: Files served as-is (favicons, uploads)resources/: Processed by Vite bundler (CSS, JS, images)No file-based routing: Explicit route definitions in routes/*.ts
No "use server/client": Clear server/client code separation
# Clone starter kit
git clone <REPO_URL>
cd <project-name>
npm install
# Add official packages
node ace add @adonisjs/static
node ace add @adonisjs/cache
# Configure packages
node ace configure @adonisjs/lucid
node ace configure @adonisjs/auth
import { codemods } from '@adonisjs/core'
await codemods.defineEnvVariables({
API_KEY: 'secret-key-here',
}, {
omitFromExample: ['API_KEY']
})
// routes/web.ts
import router from '@adonisjs/core/services/router'
const UsersController = () => import('#controllers/users_controller')
router.get('/users', [UsersController, 'index'])
router.post('/users', [UsersController, 'store'])
router.get('/users/:id', [UsersController, 'show']).param('id')
// app/controllers/users_controller.ts
import type { HttpContext } from '@adonisjs/core/http'
export default class UsersController {
async index({ request, response }: HttpContext) {
const page = request.input('page', 1)
// ... fetch users
return response.json({ data: [] })
}
async show({ params, response }: HttpContext) {
return response.json({ id: params.id })
}
}
// app/models/user.ts
import { UsersSchema } from '#database/schema'
import { column } from '@adonisjs/lucid/orm'
export default class User extends UsersSchema {
// Override serialization behavior in model layer when needed.
@column({ serializeAs: null })
declare password: string
}
// Querying (schema classes are auto-generated from migrations)
const users = await User.query().where('active', true).paginate(1, 10)
const user = await User.findOrFail(params.id)
await user.related('posts').create({ title: 'Hello' })
# v7 workflow: create model + migration, then run migrations
node ace make:model User -m
node ace migration:run
Important: Never edit database/schema.ts manually.
It is generated from migrations after migration:run.
# Install hashers
npm i argon2 # Recommended for new apps
# or
npm i bcrypt
// Basic auth setup with @adonisjs/auth
import router from '@adonisjs/core/services/router'
const AuthController = () => import('#controllers/auth_controller')
router.post('/login', [AuthController, 'login'])
router.post('/register', [AuthController, 'register'])
// app/validators/create_user.ts
import vine from '@vinejs/vine'
export const createUserValidator = vine.create({
email: vine.string().email(),
password: vine.string().minLength(8).confirmed(),
name: vine.string().minLength(2),
})
// Usage in controller
export default class UsersController {
async store({ request, response }: HttpContext) {
const data = await request.validateUsing(createUserValidator)
// ... create user
}
}
// src/extensions/request.ts
import type { Request } from '@adonisjs/core/http'
Request.macro('hasRole', function (this: Request, role: string) {
const user = this.ctx.auth.user
return user?.role === role
})
// Usage: if (request.hasRole('admin')) { ... }
// config/static.ts
{
enabled: true,
etag: true,
lastModified: true,
dotFiles: 'ignore', // Security: don't expose .env, .git
acceptRanges: true,
cacheControl: {
maxAge: '1 year',
immutable: true // For versioned/hashed filenames
}
}
import emitter from '@adonisjs/core/services/emitter'
// HTTP request completed - for logging/monitoring
emitter.on('http:request_completed', (event) => {
const { method, url } = event.ctx.request
const duration = event.duration
console.log(`${method} ${url}: ${duration}ms`)
})
// Server ready
emitter.on('http:server_ready', (event) => {
console.log(`Server running on ${event.host}:${event.port}`)
})
import type { InferRouteParams } from '@adonisjs/core/helpers/types'
// Type-safe route parameters
type UserParams = InferRouteParams<'/users/:id'>
// Result: { id: string }
import string from '@adonisjs/core/helpers/string'
import is from '@adonisjs/core/helpers/is'
string.camelCase('hello_world') // 'helloWorld'
string.slug('Hello World') // 'hello-world'
string.capitalize('hello') // 'Hello'
is.email('test@example.com') // true
is.url('https://example.com') // true
This skill combines documentation from multiple sources:
| File | Description | Pages | Confidence |
|---|---|---|---|
| api.md | API reference documentation | 1 | Medium |
| guides.md | Core feature guides | 71 | Medium |
| other.md | Stacks, starter kits, path selection | 11 | Medium |
| reference.md | Events, helpers, types | 8 | Medium |
| index.md | Documentation index | 1 | Medium |
Primary Source: Official AdonisJS Documentation (docs.adonisjs.com)
All content is derived from the official documentation with medium confidence. The documentation covers:
This skill uses a single source type (official documentation), so synthesis is straightforward:
No conflicts detected between sources - all content is from the official AdonisJS documentation.
references/other.md to understand the three application stacksreferences/tutorial.md for step-by-step learningreferences/guides.md for specific feature implementationsreferences/reference.md for events, helpers, and type utilitiesreferences/guides.md for detailed configuration| Need | File to Check |
|---|---|
| Quick answer | Quick Reference section above |
| Detailed explanation | references/guides.md |
| API method signatures | references/api.md |
| Events and listeners | references/reference.md |
| Choosing frontend stack | references/other.md |
| Step-by-step tutorial | references/tutorial.md |
router.group(() => {
router.get('/dashboard', [DashboardController, 'index'])
router.get('/profile', [ProfileController, 'show'])
}).use(middleware.auth())
import errors from '@adonisjs/core/errors'
// In your controller
try {
const user = await User.findOrFail(params.id)
} catch (error) {
if (error.code === 'E_ROW_NOT_FOUND') {
return response.notFound({ message: 'User not found' })
}
throw error
}
import db from '@adonisjs/lucid/services/db'
await db.transaction(async (trx) => {
const user = await User.create({ email: 'test@example.com' }, { client: trx })
await user.related('profile').create({ bio: 'Hello' }, { client: trx })
})
import { extname } from 'node:path'
async store({ request, response }: HttpContext) {
const coverImage = request.file('cover_image')
if (coverImage) {
const fileName = `${Date.now()}${extname(coverImage.fileName)}`
await coverImage.moveToDisk(`./${fileName}`)
}
return response.created({ message: 'Uploaded' })
}
No major discrepancies detected. All content is synthesized from the official AdonisJS documentation with medium confidence. The documentation is well-maintained and consistent.
Note: This skill targets AdonisJS v7. For older applications, validate compatibility before applying patterns from this skill.
Organized documentation extracted from official sources:
Add helper scripts here for common automation tasks:
Add templates, boilerplate, or example projects here:
To refresh this skill with updated documentation: