Best Practices

Naming conventions

Start with a verb

Name your action classes as concise, explicit phrases starting with a verb. The name should clearly describe what the action does.

Good examples:
✅ DeleteUserAction — Deletes a user
✅ SendWelcomeEmailAction — Sends a welcome email
✅ CreateCheckoutSessionAction — Creates a checkout session
✅ ResetUserPasswordAction — Resets a user's password

Bad examples:
❌ UserAction — Too vague, doesn't describe what it does
❌ UserDeleter — Uses a noun instead of a verb
❌ HandleUser — Unclear what "handle" means

Following this practice, your folder structure naturally becomes a clear catalog of all the features your application offers.

Organizing your actions

Categorize your actions

When your application grows, you might end up with a large app/actions folder. Don't hesitate to organize them into subfolders by domain or feature. Autoloading will still work correctly.

Keep actions focused, compose them for workflows

Each action should handle a single, well-defined use case. However, actions can and should call other actions to compose workflows. This allows you to build complex business processes while keeping each action focused and testable.

import { BaseAction } from '@foadonis/actions'
import Order from '#models/order'

export default class ProcessOrderAction extends BaseAction {
  // ✅ Good: Orchestrates other focused actions
  async handle(order: Order) {
    // Each step is a focused, testable action
    await ChargeUserAction.run(order.user, order.amount)
    await UpdateInventoryAction.run(order.product, order.quantity)
    await SendOrderConfirmationAction.run(order.user)
  }
}

import { BaseAction } from '@foadonis/actions'
import Order from '#models/order'

export default class ChargeOrderAction extends BaseAction {
  // ✅ Focused: Handles only charging
  async handle(order: Order) {
    // Charge customer logic
  }
}

This approach gives you the best of both worlds: focused, testable actions that can be composed into complex workflows.

Working with services

Don't throw away services

It's tempting to stop using services when you move business logic into actions. However, services are still valuable for external integrations and reusable business logic that doesn't fit into a single use case.

Keep services for:

• External API integrations (Stripe, SendGrid, etc.)
• Complex domain logic that's shared across multiple actions
• Infrastructure concerns (file storage, caching, etc.)

import Stripe from 'stripe'

export default class StripeService {
  constructor(private stripe: Stripe) {}

  async chargeCustomer(customerId: string, currency: string, amount: number) {
    return this.stripe.charges.create({
      amount,
      currency,
      customer: customerId,
    })
  }
}

import { BaseAction } from '@foadonis/actions'
import { inject } from '@adonisjs/core'
import User from '#models/user'
import StripeService from '#services/stripe_service'

@inject()
export default class ChargeUserAction extends BaseAction {
  constructor(private stripe: StripeService) {}

  async handle(user: User, amount: number) {
    await this.stripe.chargeCustomer(user.stripeId, user.currency, amount)
  }
}

Keep business logic in handle

Separate context-specific code from business logic

The handle method should contain your pure business logic, independent of how the action is invoked. Context-specific code (like reading request parameters or prompting for input) should be in asController, asCommand, or asListener.

import { BaseAction, AsController, AsCommand } from '@foadonis/actions'
import { BaseCommand } from '@adonisjs/core/ace'
import { HttpContext } from '@adonisjs/core/http'
import User from '#models/user'

export default class DeleteUserAction extends BaseAction implements AsController, AsCommand {
  // ✅ Business logic is context-agnostic
  async handle(user: User) {
    await user.delete()
  }

  // Context-specific: reads from HTTP request
  async asController({ request, response }: HttpContext) {
    const user = await User.findOrFail(request.param('id'))
    await this.handle(user)
    return response.status(204)
  }

  // Context-specific: prompts for input
  async asCommand({ prompt, logger }: BaseCommand) {
    const email = await prompt.ask('User email')
    const user = await User.findByOrFail({ email })
    await this.handle(user)
    logger.success('User deleted successfully')
  }
}

Avoid event-driven logic

Why avoid event-driven applications?

Event-driven architectures have a significant advantage: you can run logic without caring about the entrypoint. A listener can respond to user:created whether it was triggered by a registration form, an admin panel, or an import script.

However, this flexibility comes with a major drawback: it becomes really hard to retrieve the initial path that resulted in the final event. When debugging or tracing a user creation flow, you might struggle to understand:

• Where did this event originate?
• What was the original context?
• Why was this user created?

Actions provide the best of both worlds

By using actions and decoupling business logic from the entrypoint, you get the benefits of event-driven architecture while maintaining traceability:

• Decoupled business logic — The same action can be called from HTTP, CLI, or events
• Clear execution path — You can always trace back to where the action was invoked
• Testable — Actions can be tested independently without event infrastructure
• Direct action calls — Call other actions directly instead of emitting events, maintaining full traceability

export default class CreateUserAction extends BaseAction {
  // ❌ Bad: we lose traceability of the business logic
  async handle(data: CreateUserData) {
    const user = await User.create(data)
    await emitter.emit('user:registered', user)
    return user
  }
}

export default class CreateUserAction extends BaseAction {
  // ✅ Good: We know that when creating a user, a welcome email is sent
  async handle(data: CreateUserData) {
    const user = await User.create(data)
    await SendWelcomeEmailAction.run(user)
    return user
  }
}

Instead of emitting events where you lose traceability, call actions directly. This way, you can always follow the execution path and understand what happens after each step.