Run any Skill in Manus with one click

mail

Stars91

Forks11

UpdatedJuly 12, 2026 at 19:07

Transactional email in an AdonisJS app — `@adonisjs/mail` classes extending `BaseMail`, MJML templates via a shared `@email.layout` component, and `mailContext()` for appName/appUrl. Never author raw HTML+CSS blocks. Use when adding a new email, editing an existing template, testing mail with `mail.fake()`, or wiring the SMTP env. Trigger on: "add email", "send mail", "MJML template", "reset password mail", "welcome email".

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

filipebraida

filipebraida/adonisjs-starter-kit

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

More from this repository

same repository

queries

filipebraida/adonisjs-starter-kit

Read-only query patterns in an AdonisJS + Inertia app — two flavors. **List queries** for CRUD tables (Lucid paginator with search + filter + sort). **Read models** for aggregate screens (dashboards, reports) with one query per business concept composed by the controller. Types live in the query file and cross to the frontend via `import type`. Trigger on: "query", "list users", "dashboard data", "read model", "fetch data", "aggregate", "read side".

2026-07-1291

module-scaffolding

filipebraida/adonisjs-starter-kit

How to add a new module to this AdonisJS monorepo — prefer `node ace make:module`, which scaffolds and wires every touchpoint. User-invoked via /module-scaffolding when wiring a module by hand or adding a piece later.

2026-07-1291

authorization

filipebraida/adonisjs-starter-kit

RBAC + Bouncer pattern in an AdonisJS + Inertia app. Capabilities live in a `PERMISSIONS` const, role slugs in `ROLES`; a `WithRoles` mixin composes into `User` to expose `hasPermission` / `hasRole` / `syncRoles`; `BasePolicy` subclasses gate routes; the frontend consumes a typed `useCan()` prop. Escalation is protected in depth. Use when adding a capability, gating a route, adding a policy, extending role logic, or reading `can` on the frontend. Trigger on: "add permission", "gate route", "policy", "useCan", "role", "RBAC".

2026-07-1291

migrations

filipebraida/adonisjs-starter-kit

Lucid migrations in this starter kit. Convention here is **edit the existing `create_<table>_table.ts` migration + run `migration:fresh`**, not layering `alter_table` migrations on top — this is a starter kit, no production data. Migration paths are declared per module in `config/database.ts`. `app/core/database/schema.ts` is auto-generated but **committed** (models import from it, so ace cannot boot without it). Use when adding a column, adjusting an index, bootstrapping a new module's DB, or debugging migration issues. Trigger on: "add column", "migration", "alter table", "create table", "schema".

2026-07-1291

notifications

filipebraida/adonisjs-starter-kit

In-app notifications + realtime SSE in an AdonisJS + Inertia app. Stack: `@facteurjs/adonisjs` for the notification classes and delivery channels + `@adonisjs/transmit` for the SSE transport. Notifications persist to Postgres and push to a per-user SSE channel. Bell + unread badge in the logged-in shell. Emission goes through domain events. Use when adding a new notification type, wiring a listener, adding a custom SSE channel, or debugging the bell. Trigger on: "add notification", "notify user", "SSE", "bell", "facteur", "transmit".

2026-07-1291

actions-events

filipebraida/adonisjs-starter-kit

Action + event pattern for AdonisJS. Actions are single-purpose classes with `.handle(input)`; they never touch `HttpContext` and never call side-effect code (mail, notifications, transmit) directly — they emit a domain event and a listener wired in `<mod>/start/events.ts` runs the effect. Use when adding a new action, wiring a domain event, or when a listener is what should call mail/notification/transmit. Trigger on: "create action", "emit event", "add listener", "domain event".

2026-07-1291

name	mail
description	Transactional email in an AdonisJS app — `@adonisjs/mail` classes extending `BaseMail`, MJML templates via a shared `@email.layout` component, and `mailContext()` for appName/appUrl. Never author raw HTML+CSS blocks. Use when adding a new email, editing an existing template, testing mail with `mail.fake()`, or wiring the SMTP env. Trigger on: "add email", "send mail", "MJML template", "reset password mail", "welcome email".
license	MIT
allowed-tools	Read, Edit, Write, Bash, Grep, Glob

Mail

Emails are classes that extend @adonisjs/mail's BaseMail. The prepare() method sets recipients, subject, and calls this.message.htmlView('<mod>::emails/<template>', {...}). Templates are .edge files at app/<mod>/ui/emails/<name>.edge that consume a shared @email.layout component. The layout owns fonts, colors, button styles, header, and footer; each template only fills the body slot. Raw <html><head><style> blocks are never authored — MJML with the shared layout is mandatory. Emails are always dispatched from event listeners, not from actions directly (see [[actions-events]]), so unit tests can fake the emitter and end-to-end tests can fake the mail transport.

Rules

Mail class location: app/<mod>/mails/<name>_notification.ts — one file per email.
Class shape: extends BaseMail, declares from = env.get('EMAIL_FROM'), sets subject either as a class field or dynamically in prepare() from a translations field.
prepare() does all the work: build any URL (via signedUrlFor for time-limited links), call this.message.to(recipient).subject(...), then render with htmlView('<mod>::emails/<template>', props). Always spread ...mailContext() into props so the layout has appName + appUrl.
Templates live at app/<mod>/ui/emails/<name>.edge. Every template opens with @email.layout({ title, preview: subtitle }) and closes with @end. Between them, only <mj-section> markup — body, button, text.
Shared MJML layout is the single source of truth for typography, colors, header, footer. Change once, all emails update.
mailContext() returns { appName, appUrl } from env with a fallback name. Every mail class spreads it into htmlView props so the layout can render brand chrome.
Env: EMAIL_FROM required; APP_NAME optional (has a fallback); APP_URL required. SMTP vars for local dev (typically Mailpit) and the prod driver's API key (e.g. RESEND_API_KEY).
i18n: the translation shape is a plain interface (subject, title, subtitle, actionBtn, defaultMessage). Passed from the caller. Keys live per module under emails.<name>.* in the locale JSON — see [[i18n]].

Repo refs

Mail class + prepare(): app/auth/mails/reset_password_notification.ts, app/users/mails/welcome_notification.ts.
Shared MJML layout: resources/views/components/email/layout.edge. Template: app/users/ui/emails/welcome.edge.
mailContext(): app/common/services/mail_context.ts.

Doc refs

AdonisJS Mail — https://docs.adonisjs.com/guides/digging-deeper/mail
MJML documentation — https://mjml.io/documentation/
MJML in AdonisJS — https://docs.adonisjs.com/guides/digging-deeper/mail#using-mjml-for-responsive-emails

Workflow

Add a new email

Class at app/<mod>/mails/<name>_notification.ts:

import { BaseMail } from '@adonisjs/mail'
import env from '#start/env'
import { mailContext } from '#common/services/mail_context'

export default class OrderConfirmedNotification extends BaseMail {
  from = env.get('EMAIL_FROM')
  subject = 'Order confirmed'

  constructor(
    private user: User,
    private order: Order,
    private translations: MailBasicTranslation,
  ) {
    super()
    this.subject = translations.subject
  }

  async prepare() {
    const { title, subtitle, actionBtn, defaultMessage } = this.translations
    this.message.to(this.user.email).subject(this.translations.subject)
    this.message.htmlView('<mod>::emails/order_confirmed', {
      ...mailContext(),
      title,
      subtitle,
      actionBtn,
      defaultMessage,
      orderUrl: `${env.get('APP_URL')}/orders/${this.order.id}`,
    })
  }
}

Template at app/<mod>/ui/emails/<name>.edge:

@email.layout({ title, preview: subtitle })
  <mj-section background-color="#ffffff" padding="36px 40px 8px">
    <mj-column>
      <mj-text font-size="28px" font-weight="800" color="#141820">{{ title }}</mj-text>
      <mj-text padding="24px 0 0" font-size="16px" color="#3A4150">{{ subtitle }}</mj-text>
    </mj-column>
  </mj-section>

  <mj-section background-color="#ffffff" padding="0 40px 28px">
    <mj-column>
      <mj-button href="{{ orderUrl }}" align="left">{{ actionBtn }}</mj-button>
    </mj-column>
  </mj-section>
@end

Mount the edge namespace for the module — app/<mod>/start/view.ts calls edge.mount('<mod>', new URL('ui', BASE_URL)). Preload the file via adonisrc.ts — see [[module-scaffolding]].
i18n: add emails.<name>.{subject,title,subtitle,actionBtn,defaultMessage} to the locale JSON — see [[i18n]].
Trigger via event: emit the domain event from the action; the listener in <mod>/start/events.ts calls mail.send(new Mail(...)) — see [[actions-events]].
Verify: a spec that asserts the send with mail.fake() (see Testing below) — not done until it confirms the mail dispatches.

Change the shared look

Edit the shared MJML layout component. Every email updates. Ask whether a change belongs in the shared layout (font, brand color, corners) or per-template (headline size, hero image).

Signed / time-limited URLs

Use signedUrlFor('route.name', params, { expiresIn, prefixUrl, purpose }) for password-reset-style links so the URL expires and can only be consumed once.

Testing

tests/bootstrap.ts typically calls mail.fake() as a safety net so no spec accidentally emails a real inbox. Per-spec, opt into stricter assertions:

const mails = mail.fake()
await someActionThatSends()
mails.assertSent(WelcomeNotification, (msg) => msg.to === user.email)
mails.restore()

For listener specs, call mail.fake() before emitter.emit(...) — see [[testing]].

Anti-patterns

❌ Authoring <html><head><style> blocks — bypasses the layout, breaks responsive defaults, drifts from other emails.
❌ Duplicating header/footer HTML in every template — use the layout.
❌ Calling mail.send(...) directly from an action — emit an event; the listener sends. Otherwise unit tests must stub the mail service.
❌ Hardcoding appName inside a template — read {{ appName }} (provided by mailContext()).
❌ Assembling URLs by string concat when signedUrlFor (or urlFor on the frontend) is available.
❌ Forgetting preview in @email.layout({ title, preview }) — a good preview text noticeably improves inbox opens.
❌ Passing a Lucid model into the mail class and dereferencing it inside prepare() — pull the fields you need into a plain object first, so the class stays serializable and easy to test.

Related skills

[[actions-events]] · [[i18n]] · [[testing]] · [[notifications]]