Dispatching

Jobs are dispatched through a QueueClient created from the runtime. Dispatch is fully type-safe -- the payload must match the job's input schema and queue names are validated at compile time.

Creating a Client

import { queueRuntime } from "./runtime.server";

const queueClient = queueRuntime.createClient();

Dispatching a Job

import { sendEmailsJob } from "./jobs/sendEmails.job";

await queueClient.dispatch(sendEmailsJob, {
  email: "user@example.com",
  subject: "Welcome",
  body: "Hello!",
});

The second argument is type-checked against the job's input schema. Passing an incorrect shape is a compile-time error.

DispatchOptions

Pass a third argument to control retry behavior, routing, and deduplication:

await queueClient.dispatch(
  sendEmailsJob,
  { email, subject, body },
  { maxAttempts: 5, queue: "low" },
);

Options

interface DispatchOptions<TQueueName extends string> {
  maxAttempts?: number;
  queue?: TQueueName;
  delay?: number | `${number}${"ms" | "s" | "m" | "h" | "d"}`;
  dedupeKey?: string;
  meta?: Record<string, unknown>;
  session?: Session | false;
}

Option	Type	Description
maxAttempts	number	Total attempts before marking as failed
queue	TQueueName	Target queue name (defaults to first defined queue)
delay	number | string	Delay before processing. Number (ms) or string like "30s", "5m", "1h"
dedupeKey	string	Prevents duplicate jobs with the same key
meta	Record<string, unknown>	Arbitrary metadata passed through to the handler context
session	Session | false	Override auto-captured auth session. Pass false to suppress

Return Value

dispatch returns the created job's metadata:

const result = await queueClient.dispatch(sendEmailsJob, payload);
// result: { jobId: string, name: string, queue: string }

Session Propagation

By default, the current auth session (via getSession()) is automatically captured at dispatch time and restored when the worker processes the job. This means handlers can access the dispatching user's session.

Pass session: false to disable, or provide a specific session object to override.