Nuxt Processor

Scalable processing for Nuxt

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

Sections

• Install
• Upgrading from 0.x / 1.x
• Redis configuration
• Define a queue and enqueue from your app
• Define a worker
• Running
• CLI
• Bull Board
• 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.

| Config key | Dev / build | Runtime (production / Docker) | | --- | --- | --- | | redis.url | REDIS_URL | NUXT_REDIS_URL | | redis.host | REDIS_HOST | NUXT_REDIS_HOST | | redis.port | REDIS_PORT | NUXT_REDIS_PORT | | redis.password | REDIS_PASSWORD | NUXT_REDIS_PASSWORD | | redis.db | REDIS_DB | NUXT_REDIS_DB | | redis.username | REDIS_USERNAME | NUXT_REDIS_USERNAME | | redis.lazyConnect | REDIS_LAZY_CONNECT | NUXT_REDIS_LAZY_CONNECT | | redis.connectTimeout | REDIS_CONNECT_TIMEOUT | NUXT_REDIS_CONNECT_TIMEOUT |

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

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: https://github.com/felixmosh/bull-board/pull/669#issuecomment-1883997968.

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