Nuxt Processor

Background job processing for Nuxt using BullMQ with a dedicated workers process.

Note: This package is under very active development! Please consider creating issues if you run into anything!

• ✨  Release Notes
• 📖  Documentation

Features

• Dedicated processing: Workers run in a separate Node process – no coupling to your web server.
• Scalability: Run multiple worker processes and instances across machines.
• Simple DX: Define queues/workers in server/queues and server/workers using first-class helpers.

Sections

• Install
• Define a queue and enqueue from your app
• Define a worker
• Running
• CLI
• Bull Board
• Contribution

Install

npm i -D nuxt-processor

Add the module in nuxt.config.ts and set your Redis connection.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-processor'],
  processor: {
    redis: {
      host: process.env.NUXT_REDIS_HOST ?? '127.0.0.1', // defaults '127.0.0.1'
      port: Number(process.env.NUXT_REDIS_PORT ?? 6379), // defaults 6379
      password: process.env.NUXT_REDIS_PASSWORD ?? '', // defaults ''
    },
  },
})

Define a queue and enqueue from your app

Create server/queues/index.ts:

import { defineQueue } from '#processor'

export default defineQueue({
  name: 'hello',
})

Define a worker

Create server/workers/index.ts:

import { defineWorker } from '#processor'
import type { Job } from '#bullmq'

export default defineWorker({
  name: 'hello',
  async processor(job: Job) {
    // do work
    console.log('processed', job.name, job.data)
    return job.data
  },
  options: {},
})

Running

• Start your Nuxt app normally. This module generates a dedicated workers entry.
• In development, run workers from .nuxt/dev/workers/index.mjs in a separate terminal:

nuxi dev
node .nuxt/dev/workers/index.mjs

CLI

A simple CLI is provided to run workers in development.

# from your project root
npx nuxt-processor dev

Notes:

• If .nuxt/dev/workers/index.mjs does not exist yet, the CLI will ask you to start your Nuxt dev server first to generate the entry point for your workers.
• If your package.json does not have a processor:dev script, the CLI will offer to add:

{
  "scripts": {
    "processor:dev": "nuxt-processor dev"
  }
}

Then you can run:

npm run processor:dev

• After building for production, run workers from .output/server/workers/index.mjs:

nuxi build
node .output/server/workers/index.mjs

Bull Board

Bull Board is an excellent UI for watching your queues, you can follow the setup in the playground to use it.

• Server handler
• Route: playground/server/routes/bull-board.ts
• Route: playground/server/routes/bull-board/[...].ts

Special thanks to @genu for creating the H3 adapter.

For more help getting set up, see this Bull Board H3 adapter comment: felixmosh/bull-board#669 (comment).

Contribution

Local development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release