Email Notifications
Relevant source files
The following files were used as context for generating this wiki page:
Email Notifications in Farm.js function as a first-party integration within the framework's typed integration model. The system provides a standardized way to incorporate email capabilities—such as templates, delivery, and scheduling—into full-stack applications. By leveraging the integration model, the framework ensures that email providers remain typed and follow the core architectural boundaries of the application.
Sources: README.md:27-27, AGENTS.md:52-52, packages/create-farm-app/src/index.ts:117-124
Integration Architecture
Farm.js classifies email as an integration, which is a typed provider capability mounted through the framework's internal model. An integration wraps an external SDK or service (the provider) and exposes its functionality to the Farm.js core and the user application.
Data Flow and Boundaries
The framework enforces strict boundaries between server and client code. Email integrations, which typically involve sensitive credentials and server-only SDKs, reside in server-side modules to prevent exposure to the client.
The diagram below illustrates the relationship between the application, the Farm.js integration model, and the external email provider:
This diagram shows how the User Application interacts with the Email Integration through the Farm.js Core, ensuring the Provider SDK stays within the Server-Only Boundary.
Sources: AGENTS.md:52-53, AGENTS.md:92-93, ARCHITECTURE.md:14-25
The Resend Integration
The primary implementation for email notifications provided by the framework is the Resend integration. This starter template includes pre-configured patterns for common email operations.
Key Capabilities
The Resend integration encompasses four main pillars of email functionality:
| Feature | Description |
|---|---|
| Templates | Pre-defined structures for consistent email branding and content. |
| Delivery | The mechanism for transmitting emails through the Resend API. |
| Scheduling | Logic for delaying or timing email dispatches. |
| Webhooks | Handling incoming signals from the provider (e.g., delivery confirmations). |
Sources: packages/create-farm-app/src/index.ts:117-124
Routing and Discovery
Integrations often mount their own routes for UI or API interaction. The Resend integration defaults to the following paths:
- Integration Route:
/integrations/resend - Documentation Path:
/docs/integrations/email
Sources: packages/create-farm-app/src/index.ts:121-122
Implementation and Scaffolding
Developers can initialize email capabilities using the Farm.js CLI. The create-farm-app tool includes a dedicated starter for email.
Setup Procedure
- Initialize: Run
pnpm create @farm.js/appand select theresendtemplate or use the--template resendflag. - Configuration: The integration wiring is placed in
src/lib/integrationsand registered infarm.config.ts. - Environment Variables: You must copy
.env.exampleto.env.localand provide the necessary provider credentials (e.g.,RESEND_API_KEY).
Sources: packages/create-farm-app/src/index.ts:512-520, packages/create-farm-app/src/index.ts:117-124
Request Lifecycle
When a request to send an email is made, the sequence follows the framework's standard action and query flow:
This sequence diagram tracks an email request from the initial component trigger through the Server Action and Integration to the external API.
Sources: ARCHITECTURE.md:65-71, packages/create-farm-app/src/index.ts:512-520
Security and Reliability
Farm.js applies specific maintenance rules to integrations to ensure application stability:
- Error Handling: Required configuration failures must be actionable. If the email provider is unavailable, it must not prevent the application from starting or responding to other requests.
- Untrusted Input: Data passed to email templates or webhook payloads are treated as untrusted input to prevent prototype pollution or safe origin violations.
- Vendor Instances: SDK instances are kept exclusively in server-only modules.
Sources: AGENTS.md:126-130, AGENTS.md:132-134
Email Notifications in Farm.js serve as a bridge between the application logic and external delivery services, maintaining type safety and security through the standard integration architecture. By utilizing the Resend starter, developers can quickly implement reliable email delivery with minimal manual configuration.
Sources: README.md:27-27, ARCHITECTURE.md:104-106