Task Definition API

Relevant source files

• packages/build/CHANGELOG.md
• packages/build/package.json
• packages/cli-v3/CHANGELOG.md
• packages/cli-v3/package.json
• packages/core/CHANGELOG.md
• packages/core/package.json
• packages/react-hooks/CHANGELOG.md
• packages/react-hooks/package.json
• packages/rsc/CHANGELOG.md
• packages/rsc/package.json
• packages/trigger-sdk/CHANGELOG.md
• packages/trigger-sdk/package.json

Purpose and Scope

This document describes the Task Definition API provided by the @trigger.dev/sdk package, specifically the task() and schemaTask() functions used to define background tasks. It covers task configuration options, lifecycle hooks, queue settings, retry behavior, and machine presets.

For information about triggering tasks and scheduling, see Task Triggering and Scheduling. For lifecycle hook implementation details, see Lifecycle Hooks. For build-time configuration and extensions, see Build Extensions.

Task Definition Functions

The SDK provides two primary functions for defining tasks: task() for standard tasks and schemaTask() for tasks with schema-based validation.

Basic Task Structure

Sources: packages/trigger-sdk/CHANGELOG.md1-932

The task() Function

The task() function creates a standard task without payload validation. It accepts a configuration object with an id, optional settings, and a run function.

Key characteristics:

• Payload is typed as any or can be explicitly typed via TypeScript generics
• No runtime validation of payload structure
• Simpler for tasks with flexible or dynamic payloads

Sources: packages/trigger-sdk/CHANGELOG.md74-104 packages/trigger-sdk/package.json1-132

The schemaTask() Function

The schemaTask() function creates a task with Zod schema validation for both input payload and output. This provides type safety and runtime validation.

Key characteristics:

• Runtime payload validation using Zod schemas
• Automatic TypeScript type inference from schema
• Output schema validation
• JSON schema generation for task indexing

Sources: packages/trigger-sdk/CHANGELOG.md45-46 packages/trigger-sdk/CHANGELOG.md262-263 packages/core/package.json1-584

Task Configuration Options

Sources: packages/trigger-sdk/CHANGELOG.md773-801 packages/trigger-sdk/CHANGELOG.md544-545

Required Options

Option	Type	Description
id	string	Unique identifier for the task. Must be unique within the project. Used for task indexing and triggering.

Optional Options

Option	Type	Default	Description
queue	QueueOptions	-	Queue configuration for concurrency control
retry	RetryOptions	Default retry policy	Retry behavior configuration
machine	MachinePreset	"small-1x"	Machine size/resources for execution
maxDuration	number	-	Maximum execution time in seconds
jsonSchema	object	-	JSON schema for task payload (for AI SDK integration)

Sources: packages/trigger-sdk/CHANGELOG.md262-263 packages/trigger-sdk/CHANGELOG.md544-545 packages/core/CHANGELOG.md90-91

Queue Configuration

Tasks can be assigned to named queues with concurrency limits:

Queue options:

• name: String identifier for the queue
• concurrencyLimit: Maximum concurrent executions for this queue

Sources: packages/trigger-sdk/CHANGELOG.md283-288

Retry Configuration

Tasks automatically retry on failure with exponential backoff. The retry behavior can be customized:

Retry options:

• maxAttempts: Maximum number of retry attempts
• factor: Exponential backoff multiplier
• minTimeoutInMs: Minimum delay between retries
• maxTimeoutInMs: Maximum delay between retries
• default: Default retry behavior (enabled/disabled)

Sources: packages/core/CHANGELOG.md519-523

Machine Presets

Tasks can specify compute resources via machine presets:

Preset	Description
"micro"	Minimal resources
"small-1x"	Default size
"small-2x"	Double small resources
"medium-1x"	Medium resources
"large-1x"	Large resources

Machine presets can be overridden at trigger time:

Sources: packages/trigger-sdk/CHANGELOG.md773-801 packages/core/CHANGELOG.md303-331

Maximum Duration

The maxDuration option specifies the maximum execution time in seconds before the task is forcibly terminated:

Sources: packages/core/CHANGELOG.md544-545

Task Context and Metadata

Every task run receives a context object (ctx) with run-specific information:

Context properties:

• ctx.run.id: Unique run identifier
• ctx.run.attempt.number: Current attempt number (starts at 1)
• ctx.run.parentTaskRunId: Parent run ID (if triggered by another task)
• ctx.run.rootTaskRunId: Root run ID in the call chain
• ctx.run.idempotencyKey: Original idempotency key provided
• ctx.run.idempotencyKeyScope: Scope of idempotency ("run", "attempt", or "global")
• ctx.deployment: Information about the deployment

Sources: packages/trigger-sdk/CHANGELOG.md264-277 packages/trigger-sdk/CHANGELOG.md11-12

Lifecycle Hooks

Tasks support lifecycle hooks that execute at specific points during task execution:

Available Hooks

Hook	When Called	Use Case
onStartAttempt	Before each attempt (including retries)	Initialize attempt-specific resources
onSuccess	After successful completion	Cleanup, notifications, logging
onFailure	After final failure (retries exhausted)	Error reporting, rollback
onCancel	When run is cancelled	Cleanup, state restoration

Deprecated: onStart (replaced by onStartAttempt)

Hook Implementation

Important: Uncaught errors in lifecycle hooks do not fail the attempt or run. Hooks are designed to be non-blocking for observability and cleanup purposes.

Sources: packages/trigger-sdk/CHANGELOG.md66-104 packages/trigger-sdk/CHANGELOG.md325-326 packages/core/CHANGELOG.md119-120

Global Lifecycle Hooks

The SDK provides a tasks namespace for registering global lifecycle hooks that apply to all tasks:

Sources: packages/trigger-sdk/CHANGELOG.md84-91 packages/core/CHANGELOG.md333-334

Task Indexing and Metadata

When tasks are deployed, they are indexed by the platform with metadata extracted from their configuration:

Indexed metadata includes:

• Task ID (unique identifier)
• Queue name and concurrency settings
• Retry configuration
• Default machine preset
• JSON schema (for AI SDK integration and validation)

The indexing process occurs during deployment finalization and creates BackgroundWorkerTask records in the database that map task definitions to their runtime configuration.

Sources: packages/trigger-sdk/CHANGELOG.md262-263 packages/core/CHANGELOG.md519-523

AI SDK Integration

Tasks with JSON schemas can be used as tools in the Vercel AI SDK via the ai.tool() helper:

The ai.tool() function also accepts regular tasks with an explicit jsonSchema option for compatibility with AI SDK v5 and v6.

Sources: packages/trigger-sdk/CHANGELOG.md174-175 packages/trigger-sdk/CHANGELOG.md341-342 packages/trigger-sdk/package.json116-127

Task Exports and Package Structure

Tasks are exported from the @trigger.dev/sdk package with the following structure:

Import patterns:

Sources: packages/trigger-sdk/package.json23-28 packages/trigger-sdk/package.json92-127

Type Safety and Validation

The task definition API provides strong type safety through TypeScript:

Feature	Type Safety	Runtime Validation
task()	TypeScript generics	No
schemaTask()	Inferred from Zod schema	Yes
Configuration options	TypeScript interfaces	No
AI SDK integration	Schema-based	Yes

Type inference example:

Sources: packages/trigger-sdk/CHANGELOG.md45-46 packages/trigger-sdk/package.json78-88