Getting Started

Get Pidgey running in your Next.js app in minutes. This guide uses SQLite for local development—swap to PostgreSQL or Redis for production with a single config change.

Install

npm install @pidgeyjs/core @pidgeyjs/next @pidgeyjs/sqlite @pidgeyjs/cli

pnpm add @pidgeyjs/core @pidgeyjs/next @pidgeyjs/sqlite @pidgeyjs/cli

yarn add @pidgeyjs/core @pidgeyjs/next @pidgeyjs/sqlite @pidgeyjs/cli

bun add @pidgeyjs/core @pidgeyjs/next @pidgeyjs/sqlite @pidgeyjs/cli

We’ll use SQLite for this guide. For production, swap to @pidgeyjs/postgres or @pidgeyjs/redis by updating your adapter. The CLI (@pidgeyjs/cli) provides worker commands and a dashboard.

1. Create the Config

Create pidgey.config.ts in your project root:

pidgey.config.ts

import { defineConfig } from '@pidgeyjs/core';
 
export default defineConfig({
  adapter: 'sqlite',
  filename: './pidgey.db',
 
  worker: {
    jobsDir: 'jobs',
    concurrency: 10, // Number of jobs processed in parallel
    pollInterval: 1000, // Check for new jobs every 1 second
  },
});

⚡ Pidgey automatically runs migrations on startup—no manual steps required.

2. Create the Client

lib/pidgey.ts

import { Pidgey } from '@pidgeyjs/next';
import config from '../pidgey.config';
 
export const pidgey = Pidgey(config);

3. Define a Job

All files inside the jobs/ directory are automatically registered—no manual imports required.

jobs/send-email.ts

import { pidgey } from '@/lib/pidgey';
 
export const sendEmail = pidgey.defineJob({
  name: 'send-email',
  handler: async (data: { to: string; subject: string }) => {
    console.log(`📧 Sending email to ${data.to}`);
    // Your email logic here
    return { sent: true };
  },
  config: {
    retries: 3, // Retry if the job fails
    timeout: 30000, // 30 seconds timeout
  },
});

4. Enqueue Jobs

Call your job from Server Actions, API routes, or anywhere:

app/actions.ts

'use server';
 
import { sendEmail } from '@/jobs/send-email';
 
export async function handleSignup(email: string, name: string) {
  await sendEmail.enqueue(
    { to: email, subject: `Welcome, ${name}!` },
    { delay: 3600000 } // Optional: delay in milliseconds
  );
  return { success: true };
}

Trigger multiple jobs at once to see the worker in action:

await Promise.all([
  sendEmail.enqueue({ to: 'leslie@pawnee.gov', subject: 'Hello!' }),
  sendEmail.enqueue({ to: 'ben@pawnee.gov', subject: 'Welcome!' }),
]);

5. Start the Worker

npx pidgey worker dev

🔍 Discovering jobs in ./jobs
✅ Found 1 job: send-email
🚀 Worker started (concurrency: 10)

Watch your console logs as jobs are processed in real time.

6. Production Setup

Switch to PostgreSQL for production:

pidgey.config.ts

import { defineConfig } from '@pidgeyjs/core';
 
export default defineConfig({
  adapter: 'postgres',
  connection: process.env.DATABASE_URL!,
 
  worker: {
    concurrency: 50, // Higher concurrency for production
    pollInterval: 1000,
  },
});

Or Redis for high-throughput systems:

pidgey.config.ts

import { defineConfig } from '@pidgeyjs/core';
 
const adapter = process.env.JOB_ADAPTER || 'sqlite';
 
export default defineConfig(
  adapter === 'redis'
    ? { adapter: 'redis', options: { host: process.env.REDIS_HOST } }
    : adapter === 'postgres'
      ? { adapter: 'postgres', connection: process.env.DATABASE_URL }
      : { adapter: 'sqlite', filename: './dev.db' }
);

✅ All your jobs, handlers, and code remain the same—only the adapter changes.

Next Steps

CLI Dashboard — Visual job management UI
Deployment — Run workers in production
Adapters — SQLite, PostgreSQL, or Redis
Worker — Concurrency, queues, and scaling
API Reference — Full API docs
FAQ — Common questions

Introduction Jobs