next-action-backpressure

Queue rapid Next.js Server Action calls instead of letting them execute concurrently.

Why

Repeated clicks on a button can trigger multiple overlapping Server Actions. That can lead to duplicate writes, race conditions, and confusing optimistic UI state. This package adds local backpressure so actions run one at a time.

Install

npm install next-action-backpressure

Features

• Serializes actions with a shared or local queue
• Supports global queues keyed by feature name
• Includes a React hook for client components
• Optional queue strategies for replace or drop behavior
• Ships typed ESM output with no extra runtime dependencies beyond your app's React stack

Example

'use client';

import { useQueuedAction } from 'next-action-backpressure';

export function SaveButton({
  saveDraft
}: {
  saveDraft: (formData: FormData) => Promise<void>;
}) {
  const { run, isRunning, pendingCount } = useQueuedAction(saveDraft, {
    queueKey: 'draft-save'
  });

  return (
    <button disabled={isRunning} onClick={() => void run(new FormData())}>
      {isRunning ? `Saving (${pendingCount} queued)` : 'Save draft'}
    </button>
  );
}

API

useQueuedAction(action, options)

Returns:

• run: queued version of your async action
• isRunning: whether a task is currently executing
• pendingCount: number of queued calls waiting behind the current one
• activeCount: total running + queued calls
• queue: underlying ActionQueue

Options:

• queueKey: share a queue across components
• queue: provide a custom queue instance
• strategy: one of enqueue, replace-pending, or drop-while-busy
• onError: observe rejected executions

queueAction(action, options)

Wrap a function outside React and return a queued version.

getActionQueue(queueKey)

Get or create a named global queue.

Compatibility

• Node.js >=18
• Next.js 14, 15, and 16
• React 18 and 19

Reliability

• Unit-tested queue behavior for serialized execution, replacement, and busy-drop modes
• CI runs on every push and pull request
• CodeQL and Dependabot configs are included for ongoing maintenance
• Releases are prepared for npm trusted publishing with provenance

Security

Please report security issues through GitHub private vulnerability reporting when enabled, or by following SECURITY.md.

Contributing

See CONTRIBUTING.md for local development and release notes.

License

MIT