Bunnygram 🐇📬

Simple task scheduling for Next.js

⚠️

If you find inaccuracies or anything missing, please open an issue on GitHub!

Cover from Midjourney

Introduction

Bunnygram is a task scheduler for Next.js. You might need it if you want to defer a computationally expensive or long-running task in the background.

You can choose from multiple adapters, including QStash, with more coming soon.

It borrows from patterns introduced by a similar library Quirrel (opens in a new tab), which was one of the first to make adding task/job queues to Next.js more developer friendly.

Install

pnpm add bunnygram

You can also use yarn or npm.

Note that Bunnygram is 1) ESM only and 2) works with Next.js 13.2 or later (which introduces route handlers).

Setup

Suppose you wanted to send your user an email when they signed up. Here's how you can kick off the email job in the background with Bunnygram:

Step 1: Define your scheduler

Put your scheduler config somewhere e.g. tasks/send-email.ts:

// tasks/send-email.ts
 
import { makeConfig } from "bunnygram";
 
interface JobPayload {
  emailAddress: string;
}
 
interface JobResponse {
  status: boolean;
}
 
export const sendEmail = makeConfig<JobPayload, JobResponse>({
  // where the route handler will be accessible on
  route: "/api/send-email",
 
  // if you're just testing on localhost, you also need to supply the baseUrl here:
  // baseUrl: "http://localhost:3000",
 
  // the default adapter is BasicAdapter, but you can specify the one you want
  // adapter: BasicAdapter()
});

You can find out more about the config here.

Step 2: Set up a Next.js route handler

// app/api/send-email/route.ts
 
import { onReceive } from "bunnygram";
import { sendEmail } from "@/tasks/send-email";
import { mailchimp } from "example-email-api";
 
export const POST = onReceive({
  config: sendEmail,
  // the job to run
  // autocomplete 👇 on the payload
  job: async ({ payload }) => {
    const { emailAddress } = payload;
    await mailchimp.send({
      // ... use the payload
    });
    // 👇 autocomplete on the response
    return {
      status: true,
    };
  },
});

Step 3: Send a message

Send a message to the receiver from anywhere else inside our Next.js app:

// src/pages/index.tsx
 
import { send } from "bunnygram";
import { sendEmail } from "@/tasks/send-email";
 
export default function Home() {
  const runJob = async () => {
    await send({
      config: sendEmail,
      // 👇 autocomplete on the payload
      payload: {
        emailAddress: "hello@gmail.com",
      },
    });
  };
 
  return <button onClick={runJob}>Send email</button>;
}

Config