Driver Configuration

Drivers are pluggable providers for email delivery, file storage, and job queues. Each driver is an npm package that implements a typed interface, loaded dynamically at runtime based on environment variables.

How Drivers Work

You set an environment variable (e.g., EMAIL_DRIVER=toast-driver-email-mailgun)
Toast loads the package at startup using Node.js require() resolution
The driver receives its configuration (API keys, endpoints, etc.) via constructor injection
If the driver or its config is missing, the feature is disabled gracefully

Drivers never read process.env directly — all configuration is injected by the application, making them portable and testable.

Email

Email drivers handle transactional messages like magic link sign-in emails.

Console (Development Default)

Logs emails to stdout instead of sending them. No configuration needed.

# Explicitly select (or omit EMAIL_DRIVER entirely)
EMAIL_DRIVER=console

Mailgun

Production email delivery via Mailgun.

# Install the driver
pnpm add toast-driver-email-mailgun

# Configure
EMAIL_DRIVER=toast-driver-email-mailgun
EMAIL_FROM=noreply@example.com
MAILGUN_API_KEY=key-xxx
MAILGUN_DOMAIN=mg.example.com
MAILGUN_REGION=us          # "us" (default) or "eu"

Variable	Required	Description
`EMAIL_DRIVER`	Yes	`toast-driver-email-mailgun`
`EMAIL_FROM`	Yes	Default sender address
`MAILGUN_API_KEY`	Yes	Mailgun API key
`MAILGUN_DOMAIN`	Yes	Verified sending domain
`MAILGUN_REGION`	No	`us` (default) or `eu`

Resend

Community template for Resend. See the driver source for setup instructions.

EMAIL_DRIVER=toast-driver-email-resend

In production (NODE_ENV=production), EMAIL_DRIVER must be explicitly set to a real provider. The console driver is only intended for development.

Storage

Storage drivers handle file uploads (images, media).

S3-Compatible Storage

Works with any S3-compatible provider: AWS S3, Cloudflare R2, MinIO, Backblaze B2.

# Install the driver
pnpm add toast-driver-storage-s3

# Configure
STORAGE_DRIVER=toast-driver-storage-s3
S3_ENDPOINT=https://s3.amazonaws.com
S3_ACCESS_KEY_ID=AKIA...
S3_SECRET_ACCESS_KEY=wJal...
S3_BUCKET=toast-uploads
S3_REGION=us-east-1
S3_PUBLIC_URL=https://cdn.example.com

Variable	Required	Description
`STORAGE_DRIVER`	Yes	`toast-driver-storage-s3`
`S3_ENDPOINT`	Yes	Provider endpoint URL
`S3_ACCESS_KEY_ID`	Yes	Access key
`S3_SECRET_ACCESS_KEY`	Yes	Secret key
`S3_BUCKET`	Yes	Bucket name
`S3_REGION`	No	Region (default: `auto`)
`S3_PUBLIC_URL`	Yes	Public base URL for accessing uploaded files

Provider Examples

AWS S3:

S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
S3_REGION=us-east-1
S3_PUBLIC_URL=https://toast-uploads.s3.us-east-1.amazonaws.com

Cloudflare R2:

S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
S3_REGION=auto
S3_PUBLIC_URL=https://cdn.example.com

MinIO (Local Development):

S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_BUCKET=toast-uploads
S3_REGION=us-east-1
S3_PUBLIC_URL=http://localhost:9000/toast-uploads

The docker-compose.dev.yml file starts MinIO automatically with pnpm dx.

Backblaze B2:

S3_ENDPOINT=https://s3.us-west-004.backblazeb2.com
S3_REGION=us-west-004
S3_PUBLIC_URL=https://f004.backblazeb2.com/file/toast-uploads

Queues

Queue drivers handle background job processing.

In-Memory (Development Default)

Processes jobs in the current Node.js process. No configuration needed. Jobs are lost on restart.

# Omit QUEUE_DRIVER or set explicitly
QUEUE_DRIVER=memory

pg-boss (Coming Soon)

PostgreSQL-backed persistent queues via pg-boss. Uses the existing database connection — no additional infrastructure needed.

QUEUE_DRIVER=toast-driver-queue-pgboss

Feature Detection

When a driver is not configured, Toast disables the associated feature rather than failing. Use the capabilities endpoint to check what's available:

curl https://api.example.com/api/capabilities

{
  "storage": { "enabled": true, "config": { "maxUploadSize": 10485760 } },
  "email": { "enabled": true, "config": null },
  "collaboration": { "enabled": false, "config": null },
  "ai": { "enabled": false, "config": null }
}

This lets your frontend conditionally show or hide features based on the server's configuration.

Troubleshooting

"Run: pnpm add toast-driver-..."

The driver package isn't installed. Install it as a dependency of the API:

pnpm add toast-driver-storage-s3 --filter @toast/api