@buggyhunter/qjobs

@upstash/qjobs

A simple, type-safe job queue SDK for serverless environments (Next.js, Vercel, Node.js) powered by Upstash QStash.

Installation

npm install @upstash/qjobs

Setup (one-time)

Set up a catch-all route to receive and process jobs. You only need to do this once per project.

Next.js API Route

Create pages/api/jobs/[jobs].ts:

import { jobRouter } from '@upstash/qjobs';

export default jobRouter();

Next.js App Router

Create app/api/jobs/[jobs]/route.ts:

import { jobRouter } from '@upstash/qjobs';

export const POST = jobRouter();

Usage

1. Define a Job

Define your job(s) with type-safe payloads and handler logic.

import { createJob } from '@upstash/qjobs';

const emailJob = createJob('sendEmail', async (payload: { to: string; subject: string; body: string }) => {
  // Your email sending logic here
  console.log('Sending email to', payload.to);
});

2. Enqueue a Job

Enqueue jobs to be processed by your handler, either immediately or with delay/schedule.

// Enqueue a job to run immediately
await emailJob.enqueue({ to: '[e-mail]', subject: 'Hello', body: 'Welcome!' });

// Enqueue a job with a delay or schedule
await emailJob.enqueue(
  { to: '[e-mail]', subject: 'Scheduled', body: 'This will be sent later.' },
  { delay: '10s' } // or { schedule: '0 9 * * *' } for cron
);

Environment Variables

• QSTASH_TOKEN: Your Upstash QStash token (required for enqueueing jobs)
• QSTASH_SIGNING_KEY: Your Upstash QStash signing key (required for signature verification)
• VERCEL_URL or VERCEL_PROJECT_PRODUCTION_URL: (optional, for automatic URL inference)

Security & Signature Verification

This SDK automatically verifies the authenticity of incoming job requests using Upstash QStash's signature verification (via @upstash/qstash).

• Requests without a valid signature will be rejected with a 401 Unauthorized response.
• Make sure to set QSTASH_SIGNING_KEY in your environment for secure operation.

License

MIT