Quick start

Install

pnpm add @10x-media/jobs

Configure

The plugin needs at least one Payload task configured; the payload-jobs collection does not exist without one.

payload.config.ts

import { buildConfig } from 'payload'
import { jobs } from '@10x-media/jobs'

export default buildConfig({
  // ...
  jobs: {
    tasks: [
      {
        slug: 'send-welcome-email',
        inputSchema: [{ name: 'userId', type: 'text', required: true }],
        handler: async ({ input, req }) => {
          // do the work
          return { output: {} }
        },
      },
    ],
  },
  plugins: [jobs({})],
})

jobs({}) alone gives you the dashboard layer: a Status column, a queue-health bar, and error/log panels on the payload-jobs collection in the admin.

Verify

Queue a job and watch it in the admin:

await payload.jobs.queue({
  task: 'send-welcome-email',
  input: { userId: '123' },
})

Open Jobs in the admin panel. The new job appears as Queued in the health bar and the list. Run it:

await payload.jobs.run()

With deleteJobOnComplete at its default (true), a successful job disappears from the list; a failed one shows Failed with an error panel on its detail view.

Enable the production layers

Pick a topology preset to turn on reliability and queue control together:

payload.config.ts

import { jobs, singleNodePreset } from '@10x-media/jobs'

plugins: [jobs({ ...singleNodePreset() })]

Enabling reliability adds fields to payload-jobs and a payload-jobs-locks collection. On Postgres, generate and run a migration afterwards (payload migrate:create, then payload migrate).

Then run a worker as its own process, or drive the queue from cron on serverless.

Install

Configure

Verify

Enable the production layers

On this page