Queues
A queue lets you move slow work out of the request, such as sending email, resizing images, or calling a third-party API. Your route puts a job on the queue and responds right away. A separate worker process runs the job in the background.
Quick example
Create a job:
npx holo make:job emails/send-welcomeFill in what the job does:
import { defineJob } from '@holo-js/queue'
export default defineJob<{
userId: number
}>({
async handle(payload) {
console.log(`Sending welcome email to user ${payload.userId}`)
},
})Dispatch it from any server code:
import SendWelcome from '../jobs/emails/send-welcome'
export async function onUserRegistered(userId: number) {
await SendWelcome.dispatch({ userId })
}With the default sync driver, the job runs immediately inside dispatch(). No worker is needed. When you switch to the database or redis driver, the same code puts the job on a queue and a worker runs it.
Install queue support
New projects created with the queue package already have config/queue.ts and a server/jobs folder. To add queues to an existing project, run:
npx holo install queuePick a driver up front with --driver:
npx holo install queue --driver databaseThe supported values are sync (the default), database, and redis. The installer:
- creates
config/queue.tsif it doesn't exist - creates the
server/jobsfolder - adds
@holo-js/queuetopackage.json, plus@holo-js/queue-dbor@holo-js/queue-rediswhen the driver needs it - adds
QUEUE_CONNECTIONto.envand.env.example - for
redis, createsconfig/redis.tsand adds theREDIS_*variables
If config/queue.ts already exists, the installer leaves it alone and only adds missing packages.
Configure the queue
The installer writes a config like this for the sync driver:
import { defineQueueConfig } from '@holo-js/queue'
import { env } from '@holo-js/config'
export default defineQueueConfig({
default: env('QUEUE_CONNECTION', 'sync'),
failed: false,
connections: {
sync: {
driver: 'sync',
queue: 'default',
},
},
})| Key | What it does |
|---|---|
default | The connection jobs use unless they pick another one. Defaults to the first connection. |
connections | Named connections. Each has a driver (sync, database, or redis) and driver options. |
failed | Where jobs that fail on a worker are stored, or false to not store them. See Failed jobs. |
Connections and queue names
A connection picks the backend: sync, database, or redis. A queue name splits work inside one connection, such as default, emails, or media.
You can run one worker per queue name so slow work doesn't hold up fast work:
npx holo queue:work --queue emails
npx holo queue:work --queue mediaA job runs on, in order of priority:
- the connection or queue you pass when dispatching
- the
connectionorqueueset on the job - the default connection, and that connection's
queue(ordefault)
Go to production
The sync driver is fine for development, tests, and small apps. It runs jobs inside the request, so a slow job slows the response, and a failing job fails the request.
For background processing:
- Switch to the
databaseorredisdriver. - Run
queue:workas a long-running process next to your web server. - Turn on the failed jobs table so you can inspect and retry failures.
Payloads must be JSON
Job payloads are stored as JSON, so pass IDs and plain values, not model instances, Date objects, class instances, or functions. Holo rejects payloads that aren't plain JSON when you dispatch. Load the record again inside the job.
Next steps
- Writing jobs: retries, backoff, timeouts, and dispatch options
- Running workers
- Drivers and tables
- Events: fan out one action to several reactions