Nuxt BeeQueue 🐝

A powerful Nuxt module for handling background jobs using Redis and Bee-Queue. This module integrates seamlessly with Nuxt server routes and Nitro, allowing you to define, dispatch, and process jobs with ease.

Features

• Easy Job Definition: Define jobs in server/jobs using a simple API.
• Type Safety: Full TypeScript support for job payloads and returns.
• Flexible Execution: Run workers inside the Nuxt process (dev) or as separate microservices.
• Zero Configuration: Auto-imports and sensible defaults.

Installation

npm install nuxt-bee-queue
# or
yarn add nuxt-bee-queue
# or
pnpm add nuxt-bee-queue

Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['nuxt-bee-queue'],
  // Optional configuration
  queue: {
    redis: 'redis://localhost:6379',
    infernalQueue: true, // in false in dev mode queue not run automatically (must run node --watch path)
  }
})

Usage

1. Defining a Job

Create a job file in your server directory. By convention, stick to server/jobs/. Example path: server/jobs/user-create.ts

Note: The name of the file becomes the name of the queue.

You can use standard async/await or the callback style (done).

// server/jobs/user-create.ts
import { db, schema } from 'hub:db' // Example using Nuxt Hub

interface JobPayload {
  firstName: string
  lastName: string
}

// Inferred return type for Type Safety
type JobReturn = Array<typeof schema.users.$inferSelect>

export default defineJob<JobPayload, JobReturn>({
  // Option 1: Async/Await (Recommended)
  process: async (job) => {
    console.log(`Processing user: ${job.data.firstName}`)
    
    const user = await db.insert(schema.users).values({
      firstName: job.data.firstName,
      lastName: job.data.lastName,
    }).returning()
    
    console.log('User Created!')
    return user
  },

  // Option 2: Callback style
  // process: (job, done) => {
  //   // do work...
  //   done(null, result)
  // },

  setting: {
    sendEvents: false,
    removeOnSuccess: true,
  },
})

2. Dispatching a Job

You can dispatch jobs from your API routes or other server files using useQueue.

// server/api/register.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event)

  // The name 'user-create' matches the filename in server/jobs/
  const queue = useQueue('user-create')

  const job = await queue.createJob({
    firstName: body.firstName,
    lastName: body.lastName
  }).save()

  return { jobId: job.id, status: 'queued' }
})

Running Workers

Development

You have two options during development:

1. Integrated (Default): Do nothing. The queue workers will launch in the same process as your Nuxt/Nitro server.

2. Separate Process: If you want to isolate the worker logs or performance, you can run the worker separately.

Add the following to your package.json scripts:

Node:

"scripts": {
  "queue:dev": "node --watch .nuxt/dev/workers/index.mjs"
}

Bun:

"scripts": {
  "queue:dev": "bun --watch .nuxt/dev/workers/index.mjs"
}

Deno:

"scripts": {
  "queue:dev": "deno run --allow-all --watch .nuxt/dev/workers/index.mjs"
}

Production

For production deployment, the workers are built into a separate entry point.

node .output/server/workers/index.mjs

Tips & Best Practices

1. Queue Instance Management

Every time you call defineJob or useQueue('name'), a BeeQueue client instance is created. Rule: Ensure you strictly use the filename (without extension) as the queue name when dispatching.

2. Optimization (Singleton Pattern)

For optimization purposes, every BeeQueue client is stored in memory as long as the server is running. Creating a new queue instance on every request is an anti-pattern.

We highly recommend creating a wrapper for your queues to reuse the client instance.

// server/utils/queue.ts
export function useEmailQueue() {
  // This reuses the existing client if strictly created before
  return useQueue('email-sender', {
    sendEvents: false
    // ...other specific config
  })
}

Usage in API:

// server/api/send.ts
export default defineEventHandler(async () => {
  // Uses the cached connection
  await useEmailQueue().createJob({ email: '...' }).save()
})

Credits

A special thanks to Aidan Hibbard and the nuxt-processor repository. Parts of this module's architecture and logic were inspired by his work on queue processing in the Nuxt ecosystem.

License

MIT