queue/admin/frontend

@lilith/queue/admin/frontend

React hooks for BullMQ queue dashboard integration.

Installation

npm install @lilith/queue/admin/frontend

Peer dependencies:

• react ^18.0.0
• socket.io-client ^4.7.0

Usage

Setup React Query Provider

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Dashboard />
    </QueryClientProvider>
  );
}

Fetch Queue Metrics

import { useQueueMetrics } from '@lilith/queue/admin/frontend';

function Dashboard() {
  const { queues, metrics, isLoading, error } = useQueueMetrics({
    apiUrl: 'http://localhost:3000',
    refreshInterval: 5000
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {queues.map(queue => (
        <QueueCard key={queue.name} queue={queue} />
      ))}
    </div>
  );
}

Real-time WebSocket Updates

import { useQueueWebSocket } from '@lilith/queue/admin/frontend';

function LiveMetrics() {
  const { metrics, isConnected, subscribe, unsubscribe } = useQueueWebSocket({
    url: 'http://localhost:3000',
    queues: ['email-queue', 'image-processing'],
    token: 'your-auth-token' // optional
  });

  return (
    <div>
      <div>Status: {isConnected ? 'Connected' : 'Disconnected'}</div>
      {Array.from(metrics.entries()).map(([name, metric]) => (
        <MetricCard key={name} queueName={name} metrics={metric} />
      ))}
    </div>
  );
}

Fetch Jobs with Filters

import { useJobs, JobState } from '@lilith/queue/admin/frontend';

function JobList({ queueName }: { queueName: string }) {
  const [page, setPage] = useState(1);
  const [state, setState] = useState<JobState>('failed');

  const { jobs, total, totalPages, isLoading } = useJobs({
    apiUrl: 'http://localhost:3000',
    queueName,
    filters: { state, page, limit: 20 }
  });

  return (
    <div>
      <select value={state} onChange={e => setState(e.target.value as JobState)}>
        <option value="waiting">Waiting</option>
        <option value="active">Active</option>
        <option value="completed">Completed</option>
        <option value="failed">Failed</option>
      </select>

      <ul>
        {jobs.map(job => (
          <JobItem key={job.id} job={job} />
        ))}
      </ul>

      <Pagination page={page} totalPages={totalPages} onPageChange={setPage} />
    </div>
  );
}

Queue Control Operations

import { useQueueControl } from '@lilith/queue/admin/frontend';

function QueueControls({ queueName }: { queueName: string }) {
  const {
    pauseQueue,
    resumeQueue,
    cleanQueue,
    retryAllFailed,
    isPending
  } = useQueueControl({
    apiUrl: 'http://localhost:3000',
    onSuccess: (action) => {
      console.log(`${action} completed`);
    },
    onError: (action, error) => {
      console.error(`${action} failed:`, error);
    }
  });

  return (
    <div>
      <button
        onClick={() => pauseQueue({ queueName })}
        disabled={isPending}
      >
        Pause Queue
      </button>
      <button
        onClick={() => resumeQueue({ queueName })}
        disabled={isPending}
      >
        Resume Queue
      </button>
      <button
        onClick={() => cleanQueue({
          queueName,
          state: 'completed',
          grace: 3600000 // 1 hour
        })}
        disabled={isPending}
      >
        Clean Completed Jobs
      </button>
      <button
        onClick={() => retryAllFailed({ queueName })}
        disabled={isPending}
      >
        Retry All Failed
      </button>
    </div>
  );
}

Full Dashboard Component

The complete dashboard with all features integrated:

import { QueueDashboard } from '@lilith/queue/admin/frontend';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <QueueDashboard
        apiUrl="http://localhost:3000/api/admin"
        wsUrl="http://localhost:3000"
        refreshInterval={5000}
        enableWebSocket={true}
        onError={(error) => console.error('Dashboard error:', error)}
      />
    </QueryClientProvider>
  );
}

API

Components

• QueueDashboard - Main dashboard with queue list, job browser, and DLQ manager
• QueueList - List of queue cards with selection support
• QueueCard - Single queue card displaying status and metrics
• JobsTable - Paginated table of jobs with filters and detail modal
• JobDetailsModal - Modal showing complete job data and error traces
• DLQManager - Dead letter queue management for failed jobs

Hooks

• useQueueMetrics(options) - Fetch queue list and metrics with auto-refresh
• useQueueWebSocket(options) - Subscribe to real-time queue metrics via WebSocket
• useJobs(options) - Fetch paginated jobs with filters
• useQueueControl(options) - Mutations for pause, resume, clean, retry operations

Types

All TypeScript types are exported from the main entry point:

import type {
  QueueSummary,
  QueueMetrics,
  JobDetails,
  JobState,
  JobFilters,
  DLQItem,
  PaginatedResponse,
  QueueControlOptions,
  CleanQueueOptions,
  RetryJobOptions,
  RetryAllFailedOptions,
} from '@lilith/queue/admin/frontend';

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

License

MIT