nuxt-queue

library0.4.4jsnpmunverified

Nuxt Queue v0.4.4 is an event-sourced queue and flow orchestration module for Nuxt, built on BullMQ with Redis. It provides reliable job processing, multi-step workflows with event sourcing, real-time monitoring via a Vue Flow dev UI, and horizontal scaling support. Key differentiators include auto-discovery of workers from the filesystem, integrated scheduling (cron/delay), and a worker context with state, logging, and events. Active development with planned Python workers and Postgres adapters. Requires Redis, Nuxt 3, and Node >=18.

devops

npm install nuxt-queue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NUXT-QUEUE

nuxt-queue

devopsjavascriptv0.4.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineQueueWorker

✓ import { defineQueueWorker } from 'nuxt-queue'

✗ const { defineQueueWorker } = require('nuxt-queue')

ESM-only package. defineQueueWorker is used in server/queues/*/process.ts files.

defineQueueConfig

✓ import { defineQueueConfig } from 'nuxt-queue'

Used to export config alongside worker definition.

enqueueJob

✓ import { enqueueJob } from 'nuxt-queue/server'

✗ import { enqueueJob } from 'nuxt-queue'

enqueueJob is exported from 'nuxt-queue/server' subpath, not the root module.

QueueModuleOptions

✓ import type { QueueModuleOptions } from 'nuxt-queue'

✗ import { QueueModuleOptions } from 'nuxt-queue'

TypeScript type, should be imported with type syntax.

Shows full setup: Nuxt config with Redis, a worker definition with config, and an API route to enqueue jobs.

// nuxt.config.ts export default defineNuxtConfig({ modules: ['nuxt-queue'], queue: { ui: true, store: { adapter: 'redis', redis: { host: process.env.REDIS_HOST ?? '127.0.0.1', port: Number(process.env.REDIS_PORT ?? 6379), }, }, }, }) // server/queues/example/process.ts export default defineQueueWorker(async (job, ctx) => { const { message } = job.data ctx.logger.log('info', 'Processing', { message }) await ctx.state.set('processedAt', new Date().toISOString()) return { success: true, processed: message } }) export const config = defineQueueConfig({ concurrency: 5 }) // server/api/enqueue.post.ts export default defineEventHandler(async (event) => { const { enqueueJob } = await import('nuxt-queue/server') const job = await enqueueJob('example', { message: 'Hello' }) return { jobId: job.id } })

Debug

Known issues

breakingVersion 0.4.0 changed the event store schema. Old events are not compatible.

fix

Delete old Redis streams or migrate event data to new schema (see v0.4 migration guide).

affects: <0.4.0

gotchaWorkers are auto-discovered from the filesystem; any file in server/queues/**/process.ts is registered. Accidental exports can cause unexpected queues.

fix

Ensure only intended worker files are placed under server/queues/. Use explicit naming conventions.

affects: >=0.1.0

gotchaThe dev UI requires ui: true in config and only works in development mode (nuxt dev). Enabled in production by mistake.

fix

Set queue.ui to false or conditionally set based on NODE_ENV.

affects: >=0.4.0

deprecatedThe 'queue' and 'state' adapter config keys are deprecated in favor of the unified 'store' config.

fix

Use the 'store' object to configure Redis for both queue and state.

affects: >=0.4.0

gotchaenqueueJob must be imported from 'nuxt-queue/server', not 'nuxt-queue'. Root only exports server-side utilities.

fix

Use import { enqueueJob } from 'nuxt-queue/server'.

affects: >=0.4.0

Errors

Common errors & fixes

Cannot find module 'nuxt-queue/server' or its corresponding type declarations.

Missing subpath exports in older versions or incorrect tsconfig paths.

fix

Update nuxt-queue to >=0.4.0, ensure tsconfig includes 'moduleResolution': 'bundler' or 'node16'.

Error: Redis connection refused at 127.0.0.1:6379

Redis is not running or misconfigured.

fix

Check Redis service status and verify host/port in queue.store.redis config.

TypeError: ctx.state.set is not a function

State adapter not configured or misconfigured.

fix

Ensure store.adapter is set to 'redis' or configure state adapter explicitly.

ERROR [nitro] Cannot stringify response: [object Object]

Returning a non-serializable object from a worker (e.g., containing functions).

fix

Return only plain JSON-serializable data from worker process function.

Upgrade

Version history

0.4.4latest on npm

Audit

Dependencies

@nuxt/kitrequiredRequired for Nuxt module integration

bullmqrequiredUnderlying queue and job processing engine

ioredisrequiredRedis client for BullMQ and event sourcing

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/DevJoghurt/nuxt-queue ↗

packagenuxt-queue ↗

homepagehttps://github.com/DevJoghurt/nuxt-queue#readme ↗