fastify-queue

library1.3.0jsnpmunverified

A Fastify plugin that integrates BullMQ through file-based Queue and Worker creation. Version 1.3.0 is the latest stable release. It uses a glob pattern (bullPath) to automatically discover and register BullMQ queues and workers from the filesystem. TypeScript types are included. Key differentiators: automatic file-based discovery eliminates manual queue/worker registration; supports exporting queueConfig and workerConfig options alongside worker functions. This plugin is lightweight and designed specifically for Fastify applications needing job queues. It requires fastify >=3.24.1 and bullmq ^1.59.4 || ^5.0.0 as peer dependencies.

devops

npm install fastify-queue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FASTIFY-QUEUE

fastify-queue

devopsjavascriptv1.3.0

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.

default

✓ import queue from 'fastify-queue'

✗ const queue = require('fastify-queue')

ESM-only package; the default export is a Fastify plugin function. Using require will fail.

FastifyQueueOptions

✓ import type { FastifyQueueOptions } from 'fastify-queue'

✗ import { FastifyQueueOptions } from 'fastify-queue'

Type import for TypeScript; runtime import will cause error because the type is not value-exported.

default

✓ import queue, { FastifyQueueOptions } from 'fastify-queue'

✗ const { default: queue } = require('fastify-queue')

In CJS, default export is accessed via .default. But the package is ESM-only, so require is not recommended.

Registers fastify-queue with Redis connection and glob pattern, TypeScript augmentation for queue/worker access.

import fp from 'fastify-plugin'; import queue from 'fastify-queue'; import { FastifyQueueOptions } from 'fastify-queue'; import IORedis from 'ioredis'; import Fastify from 'fastify'; const app = Fastify(); app.register(fp<FastifyQueueOptions>(async (fastify, opts) => { const connection = new IORedis({ maxRetriesPerRequest: null, enableReadyCheck: false, }); await fastify.register(queue, { bullPath: '*/bull/**/*.js', connection, }); })); // After registration, access queues and workers app.ready().then(() => { // app.queues and app.workers are available after TypeScript augmentation console.log('Plugin registered'); });

Debug

Known issues

deprecatedThe bullPath option requires a glob pattern that only matches .js files; .ts files are not compiled at runtime.

fix

Ensure your TypeScript worker files are compiled to .js before runtime, or adjust bullPath to match .ts if using ts-node.

affects: >=1.0.0

breakingBullMQ version 5 introduced breaking changes; this plugin supports bullmq ^1.59.4 || ^5.0.0 but behavior may differ.

fix

Check BullMQ v5 migration guide if upgrading from BullMQ 1.x.

affects: >=1.0.0

gotchaThe plugin automatically creates queues and workers; if a worker file does not export a default function, only a queue is created without a worker.

fix

Ensure each worker file exports a default async function to create a worker; otherwise, only a queue is registered.

affects: >=1.0.0

gotchaQueue names are derived from subdirectory names under bullPath; file names inside subdirectories are ignored.

fix

Structure files as subdirectories inside the bull path, e.g., bull/user/*.worker.ts creates queue named 'user'.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'fastify-queue' or its corresponding type declarations.

Package not installed or TypeScript cannot resolve types.

fix

Run npm install fastify-queue and ensure tsconfig.json includes node_modules types.

Property 'queues' does not exist on type 'FastifyInstance'.

TypeScript augmentation not declared.

fix

Declare module augmentation as shown in README: declare module 'fastify' { interface FastifyInstance { queues: {...}; workers: {...} } }

Error: Cannot find module 'bullmq'

Peer dependency bullmq is not installed.

fix

Run npm install bullmq

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

bullmqrequiredrequired peer dependency for queue/worker functionality

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/JonasHiltl/fastify-queue ↗

packagefastify-queue ↗

homepagehttps://github.com/JonasHiltl/fastify-queue ↗