Background Jobs & Triggers
Relevant source files
The following files were used as context for generating this wiki page:
Background Jobs and Triggers in Farm.js enable the execution of long-running or deferred tasks outside the main request-response cycle. This system uses a typed integration model to wrap external providers, ensuring that background work remains type-safe and consistent with the rest of the application. The framework provides first-party integration support for providers like Inngest and Trigger.dev through a unified jobs(...) entry point.
Sources: examples/jobs-integration/src/app/page.tsx:32-35, README.md:28-28, AGENTS.md:57-58
Job Lifecycle and Execution Flow
The framework manages job execution by providing a typed caller (api.jobs.*) that interacts with a mounted runtime. When a task is triggered, the framework communicates with the selected provider to queue the work. The status of these tasks can then be polled or monitored via generated status routes.
Task Triggering Process
This diagram illustrates the flow from a server-side trigger call to the background worker.
The sequence shows how the typed caller initiates work and subsequently retrieves the status using a unique identifier.
Sources: examples/jobs-integration/src/app/page.tsx:3-23, examples/jobs-integration/src/app/page.tsx:43-45
Integration and Configuration
Farm.js employs an integration model where background job capabilities are mounted via specific provider packages. The framework supports multiple runtimes while maintaining a small public API surface.
Supported Providers
The following table lists the primary background job providers supported through the create-farm-app templates and integration system.
| Provider | Description | Starter Template |
|---|---|---|
| Inngest | Typed background jobs backed by Inngest. | jobs-inngest |
| Trigger.dev | Typed background jobs backed by Trigger.dev. | jobs-trigger |
Sources: packages/create-farm-app/src/index.ts:110-121, examples/jobs-integration/src/app/page.tsx:34-36
Task Metadata Structure
Each task managed by the jobs integration exposes a set of metadata properties used for monitoring and routing.
| Field | Description |
|---|---|
key | The unique identifier for the task within the app. |
runtime | The selected job runtime (e.g., "inngest", "trigger"). |
id | The framework-specific internal task ID. |
remoteId | The ID assigned by the external provider. |
paths.trigger | The API route used to trigger the task. |
paths.status | The API route used to check task status. |
configured | Boolean indicating if required environment variables are present. |
Sources: examples/jobs-integration/src/app/page.tsx:55-75
Implementation Patterns
Triggering Tasks
Tasks are triggered using the trigger method on the specific job object within the api.jobs namespace. Users can pass data in the body and execution controls (like delays or tags) in the $options object.
// Example: Triggering a task with Trigger.dev
const queued = await api.jobs.sendWelcomeEmail.trigger({
body: {
userId: "usr_123",
$options: {
delay: "10m",
tags: ["signup"],
},
},
});
Sources: examples/jobs-integration/src/app/page.tsx:3-12
Monitoring Status
After triggering a task, the status method retrieves the current state of execution using the handleId returned during the trigger phase.
// Example: Checking task status
const status = await api.jobs.importCsv.status({
query: { handleId: queued.data!.handleId },
});
Sources: examples/jobs-integration/src/app/page.tsx:21-23, examples/jobs-integration/src/app/page.tsx:71-72
Architecture Principles
The Background Jobs system adheres to the core Farm.js architectural promises:
- Typed Conventions: Task maps and callers are fully typed, causing build-time failures if parameters or task names are incorrect.
- Predictable Boundaries: Job logic remains on the server, and credentials for providers are kept in server-only modules or environment variables.
- Small API Surface: The framework uses a single
jobs(...)integration entry point to mount provider-specific logic.
Sources: AGENTS.md:17-21, examples/jobs-integration/src/app/page.tsx:33-35, ARCHITECTURE.md:46-51
Related Systems
Background Jobs often interact with other framework modules to complete complex workflows:
- Cron Handlers: For scheduled execution rather than ad-hoc triggers. Sources: packages/farm-devtools/src/panel.ts:182-186
- KV Storage: Used for persisting task-related data or state across retries. Sources: ARCHITECTURE.md:38-38
- Middleware: Can be used to protect trigger routes or inspect task headers. Sources: ARCHITECTURE.md:143-147
This system provides a robust foundation for building reliable, scalable background processing into Farm.js applications by leveraging specialized external runtimes while maintaining a unified developer experience.