Registry / devops / payload-hooks-queue

payload-hooks-queue

library0.0.1jsnpmunverified

A lightweight utility for deferring Payload CMS collection hooks into background jobs or workflows. Version 0.0.1 is the initial release, designed for Payload 2.x+. It captures hook payloads (beforeChange, afterChange, etc.) and pushes them to a queue for async processing, reducing request latency and preventing hook failures from blocking API responses. Unlike custom job runners, it integrates directly with Payload's hook system and can work with any queue backend (Bull, Redis, etc.) via a simple adapter pattern. Ships TypeScript types.

devops storage

npm install payload-hooks-queue

package ↗

INSTALL

IMPORT

SIG · PAYLOAD-HOOKS-QUEU

payload-hooks-queue

devopsjavascriptv0.0.1

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.

createHookQueue

✓ import { createHookQueue } from 'payload-hooks-queue'

✗ const createHookQueue = require('payload-hooks-queue')

Package is ESM-only; CommonJS require will not work.

QueuePayload

✓ import type { QueuePayload } from 'payload-hooks-queue'

✗ import { QueuePayload } from 'payload-hooks-queue'

QueuePayload is a type (interface) and should be imported with import type in TypeScript to avoid runtime errors.

HookEventType

✓ import { HookEventType } from 'payload-hooks-queue'

HookEventType is a runtime enum; named import is correct.

Creates a Bull queue adapter and attaches it to a Payload collection's afterChange hook for async processing.

import { createHookQueue } from 'payload-hooks-queue'; import { CollectionConfig } from 'payload/types'; const myQueue = createHookQueue({ type: 'bull', options: { redis: { host: 'localhost', port: 6379 }, }, }); export const MyCollection: CollectionConfig = { slug: 'items', hooks: { afterChange: [ myQueue.enqueue({ handler: async (args) => { // background processing console.log('Processing doc', args.doc.id); }, }), ], }, fields: [], };

Debug

Known issues

gotchaThe queue adapter (Bull in this example) must be installed separately; payload-hooks-queue does not bundle it.

fix

Install the queue adapter: npm install bull (or redis, etc.)

affects: >=0.0.0

breakingInitial release (0.0.1); all APIs are experimental and may change without major version bump.

fix

Pin to a specific version and test upgrades thoroughly.

affects: 0.0.1

gotchaHooks run asynchronously; if the queue fails to enqueue, the hook will reject, potentially causing request failure. Ensure queue connection is resilient.

fix

Wrap enqueue in try/catch or use a fallback synchronous handler.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'payload-hooks-queue'

Package not installed or missing from package.json

fix

npm install payload-hooks-queue

TypeError: createHookQueue is not a function

CommonJS require used instead of ESM import; this package is ESM-only.

fix

Use import { createHookQueue } from 'payload-hooks-queue' and ensure "type": "module" in package.json or use .mjs extension.

TypeError: AfterChange hook must be an array of functions

enqueue() returns an object, but Payload expects a function. The returned object is not compatible directly.

fix

Ensure the hook array item is the result of myQueue.enqueue({...}) which returns a function wrapping the queued handler.

Upgrade

Version history

0.0.1latest on npm

Audit

Dependencies

payloadrequiredPeer dependency: integrates with Payload CMS collection hooks

Agent activity

6 hits · last 30 days

node

Resources

packagepayload-hooks-queue ↗