DocumentationGetting Started

Getting Started

Learn Pidgey

Get Pidgey running in your Next.js app.

Install

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

We’ll use SQLite for this guide. For production, swap to @pidgeyjs/postgres or @pidgeyjs/redis with a one-line config change.

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,
  },
});

This single config is used by both your app and the CLI worker.

2. Create the Client

lib/pidgey.ts
import { Pidgey } from '@pidgeyjs/next';
import config from '../pidgey.config';
 
export const pidgey = Pidgey(config);
Migrations run automatically on first use.

3. Define a Job

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,
    timeout: 30000,
  },
});

4. Enqueue Jobs

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 }
  );
  return { success: true };
}

5. Start the Worker

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

6. Test It

Trigger your action. You’ll see the worker process the job:

📧 Sending email to leslie.knope@pawnee.gov
✅ Job completed: job_abc123

Production Setup

Switch to PostgreSQL by updating your config:

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

Your jobs, handlers, and code stay the same—only the adapter changes.

Next Steps

IntroductionJobs