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'
import nitroProcessor from 'nitro-processor'

export default defineConfig({
  modules: [
    nitroProcessor({ workers: 'server/workers' }),
  ],
})

Vite + Nitro (vite.config.ts)

import { defineConfig } from 'vite'
import { nitro } from 'nitro/vite'
import nitroProcessor from 'nitro-processor'

export default defineConfig({
  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'

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

Define a worker

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

export default defineWorker({
  name: 'hello',
  async processor(job: Job) {
    console.log('processed', job.name, job.data)
    return job.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