Nuxt Processor

Scalable processing for Nuxt

Looking for Nitro v3 support? Checkout nitro-processor.

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

Upgrading from 0.x or 1.x? Redis config and the workers registry changed in v2 — see the upgrading guide.

Using an LLM? Documentation markdown is included in the package at node_modules/nuxt-processor/docs/

• ✨  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 using first-class helpers.

Used by

Also using Nuxt Processor? Open an issue to get your businesses logo added below!

Sections

• Install
• Upgrading from 0.x / 1.x
• Redis configuration
• Define a queue and enqueue from your app
• Define a worker
• Running
• CLI
• Durabull
• Contribution

Install

npx nuxi@latest module add nuxt-processor@latest

Add the module in nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-processor'],
})

Redis configuration

Using Valkey? Read this thread.

Configure Redis via runtime config: REDIS_* in dev/build, NUXT_REDIS_* at runtime (details · docs). API: docs/API.

Dev / build — in the .env file (loaded by the Nuxt CLI during nuxi dev and nuxi build):

REDIS_URL=redis://127.0.0.1:6379/0

Optional (same as 0.x): REDIS_USERNAME, REDIS_LAZY_CONNECT=true, REDIS_CONNECT_TIMEOUT=10000. See Redis configuration.

Docker / production — set NUXT_REDIS_* on the running container on both the app and workers services (details):

environment:
  NUXT_REDIS_URL: redis://redis:6379/0

Or when starting the built server directly:

NUXT_REDIS_URL=redis://127.0.0.1:6379/0 node .output/server/workers/index.mjs

Use the same Redis settings on the Nuxt app and workers process. If nothing is set, ioredis defaults to 127.0.0.1:6379.

Module option: processor.workers (default server/workers) — folder scanned for worker files.

Define a queue and enqueue from your app

Create server/queues/hello.ts:

import { defineQueue } from '#processor'

type HelloName = 'hello'
type HelloData = { message: string, ts: number }
type HelloResult = { echoed: string, processedAt: number }

export default defineQueue<HelloData, HelloResult, HelloName>({
  name: 'hello',
  options: {},
})

Define a worker

Create server/workers/hello.ts:

import { defineWorker } from '#processor'

type HelloName = 'hello'
type HelloData = { message: string, ts: number }
type HelloResult = { echoed: string, processedAt: number }

export default defineWorker<HelloName, HelloData, HelloResult>({
  name: 'hello',
  async processor(job) {
    return { echoed: job.data.message, processedAt: job.data.ts }
  },
  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

By default all workers run. To run only specific workers, use the --workers= flag with a comma-separated list of worker names:

node .nuxt/dev/workers/index.mjs --workers=basic,hello

CLI

A simple CLI is provided to run workers in development (with file watching and restarts).

# from your project root – runs all workers
npx nuxt-processor dev

# run only specific workers
npx nuxt-processor dev --workers=basic,hello

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

To run only specific workers in production:

node .output/server/workers/index.mjs --workers=basic,hello

Durabull

Durabull is a modern BullMQ dashboard for watching queues, inspecting jobs, and debugging failures. Run it alongside your Nuxt app and point it at the same Redis connection used by Nuxt Processor:

docker run --rm -p 127.0.0.1:3000:3000 \
  -e DURABULL_AUTHLESS=true \
  -e DURABULL_ENV_CONNECTIONS=true \
  -e DURABULL_REDIS_URL_ENCRYPTION_KEY=$(openssl rand -hex 32) \
  -e DURABULL_REDIS_URL_MAIN=redis://host.docker.internal:6379/0 \
  -e DURABULL_REDIS_URL_MAIN_ENVIRONMENT=development \
  -e DURABULL_REDIS_URL_DEFAULT=MAIN \
  -e APP_BASE_URL=http://localhost:3000 \
  -e VITE_PUBLIC_APP_URL=http://localhost:3000 \
  ghcr.io/durabullhq/durabull:latest

Then open http://localhost:3000 and select the MAIN connection. If Redis runs in another container, put Durabull on the same Docker network and use that Redis service name instead of host.docker.internal.

For more options, see the dedicated Durabull guide and the Durabull self-hosting docs.

Contribution

See CONTRIBUTING.md for setup, tests, and pull requests. Please follow our Code of Conduct.

Quick start:

npm install
npm run dev:prepare
npm run dev
npm run ci