Nitro Processor

Looking for Nuxt? This package is for standalone Nitro and Vite + Nitro apps. For Nuxt, use nuxt-processor.

Scalable processing for Nitro

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

Using an LLM? Documentation markdown is included in the package at node_modules/nitro-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.

Sections

• Install
• Configuration
• Redis configuration
• Define a queue and enqueue from your app
• Define a worker
• Running
• CLI
• Durabull
• Contribution

Install

npm install nitro-processor

Configuration

Register the module in nitro.config.ts (standalone Nitro) or vite.config.ts (Vite + Nitro plugin). Full reference: Configuration.

Standalone Nitro (nitro.config.ts)

import{defineConfig}from'nitro/config'importnitroProcessorfrom'nitro-processor'exportdefaultdefineConfig({modules: [nitroProcessor({workers: 'server/workers'}),],})

Vite + Nitro (vite.config.ts)

import{defineConfig}from'vite'import{nitro}from'nitro/vite'importnitroProcessorfrom'nitro-processor'exportdefaultdefineConfig({plugins: [nitro()],nitro: {modules: [nitroProcessor({workers: 'server/workers'}),],},})

You can also use a separate nitro.config.ts alongside the Vite plugin — see the configuration guide.

buildDir and the workers CLI

Dev workers are emitted at {buildDir}/dev/workers/index.mjs (default node_modules/.nitro/dev/workers/index.mjs). If you set a custom buildDir in Nitro config, pass it to the CLI:

npx nitro-processor dev --buildDir .nitro
# or
NITRO_PROCESSOR_BUILD_DIR=.nitro npx nitro-processor dev

Redis configuration

Configure Redis with Nitro runtime config.

Phase	Env prefix	Example
Dev / build	REDIS_*	REDIS_URL=redis://127.0.0.1:6379/0
Runtime (prod/Docker)	NITRO_REDIS_*	NITRO_REDIS_URL=redis://redis:6379/0

See Redis configuration for the full reference.

Define a queue and enqueue from your app

import{defineQueue}from'#processor'// or: import { defineQueue } from 'nitro-processor/runtime'exportdefaultdefineQueue({name: 'hello',})

Define a worker

import{defineWorker}from'#processor'importtype{Job}from'#bullmq'exportdefaultdefineWorker({name: 'hello',asyncprocessor(job: Job){console.log('processed',job.name,job.data)returnjob.data},})

Running

• Start your Nitro app first (nitro dev or vite dev). This module generates a dedicated workers entry under {buildDir}/dev/workers/index.mjs (default node_modules/.nitro/dev/workers/index.mjs).
• In development, run workers from that entry in a separate terminal.

nitro dev # or: vite dev
npx nitro-processor dev

CLI

# runs all workers
npx nitro-processor dev
# run only specific workers
npx nitro-processor dev --workers=basic,hello
# custom buildDir (must match nitro.config.ts / vite.config.ts)
npx nitro-processor dev --buildDir .nitro

After building for production:

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

Durabull

See the Durabull guide.

Contribution

See CONTRIBUTING.md.

npm install
npm run dev:prepare
npm run ci