12 | 13 |
20 |
21 | > Cover from Midjourney
22 |
23 | ## Introduction
24 |
25 | 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.
26 |
27 | You can choose from multiple adapters, including [QStash](/adapters/qstash), with more coming soon.
28 |
29 | It borrows from patterns introduced by a similar library [Quirrel](https://github.com/quirrel-dev/quirrel), which was one of the first to make adding task/job queues to Next.js more developer friendly.
30 |
31 | ## Install
32 |
33 | ```sh
34 | pnpm add bunnygram
35 | ```
36 |
37 | You can also use `yarn` or `npm`.
38 |
39 | Note that Bunnygram is 1) ESM only and 2) works with Next.js 13.2 or later (which introduces route handlers).
40 |
41 | ## Setup
42 |
43 | 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:
44 |
45 | ### Step 1: Define your scheduler
46 |
47 | Put your scheduler config somewhere e.g. `tasks/send-email.ts`:
48 |
49 | ```ts
50 | // tasks/send-email.ts
51 |
52 | import { makeConfig } from "bunnygram";
53 |
54 | interface JobPayload {
55 | emailAddress: string;
56 | }
57 |
58 | interface JobResponse {
59 | status: boolean;
60 | }
61 |
62 | export const sendEmail = makeConfigMIT {new Date().getFullYear()} © Bunnygram.
, 26 | }, 27 | project: { 28 | link: "https://github.com/sarimabbas/bunnygram", 29 | }, 30 | docsRepositoryBase: 31 | "https://github.com/sarimabbas/bunnygram/tree/main/packages/docs", 32 | }; 33 | 34 | export default config; 35 | -------------------------------------------------------------------------------- /packages/docs/tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "target": "es5", 4 | "lib": [ 5 | "dom", 6 | "dom.iterable", 7 | "esnext" 8 | ], 9 | "allowJs": true, 10 | "skipLibCheck": true, 11 | "strict": true, 12 | "forceConsistentCasingInFileNames": true, 13 | "noEmit": true, 14 | "esModuleInterop": true, 15 | "module": "esnext", 16 | "moduleResolution": "node", 17 | "resolveJsonModule": true, 18 | "isolatedModules": true, 19 | "jsx": "preserve", 20 | "incremental": true, 21 | "baseUrl": ".", 22 | "paths": { 23 | "@/*": [ 24 | "./*" 25 | ] 26 | } 27 | }, 28 | "include": [ 29 | "next-env.d.ts", 30 | "**/*.ts", 31 | "**/*.tsx", 32 | ], 33 | "exclude": [ 34 | "node_modules" 35 | ] 36 | } -------------------------------------------------------------------------------- /packages/nextjs-example/.gitignore: -------------------------------------------------------------------------------- 1 | # See https://help.github.com/articles/ignoring-files/ for more about ignoring files. 2 | 3 | # dependencies 4 | /node_modules 5 | /.pnp 6 | .pnp.js 7 | 8 | # testing 9 | /coverage 10 | 11 | # next.js 12 | /.next/ 13 | /out/ 14 | 15 | # production 16 | /build 17 | 18 | # misc 19 | .DS_Store 20 | *.pem 21 | 22 | # debug 23 | npm-debug.log* 24 | yarn-debug.log* 25 | yarn-error.log* 26 | .pnpm-debug.log* 27 | 28 | # local env files 29 | .env*.local 30 | 31 | # vercel 32 | .vercel 33 | 34 | # typescript 35 | *.tsbuildinfo 36 | next-env.d.ts 37 | -------------------------------------------------------------------------------- /packages/nextjs-example/.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "typescript.tsdk": "../../node_modules/.pnpm/typescript@5.0.4/node_modules/typescript/lib", 3 | "typescript.enablePromptUseWorkspaceTsdk": true 4 | } 5 | -------------------------------------------------------------------------------- /packages/nextjs-example/CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # bunnygram-test 2 | 3 | ## 1.0.0 4 | 5 | ### Major Changes 6 | 7 | - Breaking change: 8 | 9 | This version updates bunnygram to use Fetch API and work with Next.js 13.2 route handlers inside the `app` directory. Bunnygram will no longer work with `pages` directory API routes. 10 | 11 | Why this change was made: 12 | 13 | The ecosystem seems to be moving towards the new `app` directory, and this change simplifies Bunnygram's code significantly. 14 | 15 | How you should update your code: 16 | 17 | Please consult the docs for how to update your code. The minimum required Next.js version is 13.2. The code changes are minimal (mostly moving from `pages` to `app` directory). Please open an issue if you encounter buggy behavior. Thanks! 18 | 19 | ### Patch Changes 20 | 21 | - Updated dependencies 22 | - bunnygram@2.0.0 23 | -------------------------------------------------------------------------------- /packages/nextjs-example/README.md: -------------------------------------------------------------------------------- 1 | This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app). 2 | 3 | ## Getting Started 4 | 5 | First, run the development server: 6 | 7 | ```bash 8 | npm run dev 9 | # or 10 | yarn dev 11 | # or 12 | pnpm dev 13 | ``` 14 | 15 | Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. 16 | 17 | You can start editing the page by modifying `pages/index.tsx`. The page auto-updates as you edit the file. 18 | 19 | [API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.ts`. 20 | 21 | The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages. 22 | 23 | This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font. 24 | 25 | ## Learn More 26 | 27 | To learn more about Next.js, take a look at the following resources: 28 | 29 | - [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. 30 | - [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. 31 | 32 | You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome! 33 | 34 | ## Deploy on Vercel 35 | 36 | The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. 37 | 38 | Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details. 39 | -------------------------------------------------------------------------------- /packages/nextjs-example/next.config.js: -------------------------------------------------------------------------------- 1 | /** @type {import('next').NextConfig} */ 2 | const nextConfig = { 3 | reactStrictMode: true, 4 | experimental: { 5 | appDir: true, 6 | }, 7 | }; 8 | 9 | module.exports = nextConfig; 10 | -------------------------------------------------------------------------------- /packages/nextjs-example/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "bunnygram-test", 3 | "version": "1.0.0", 4 | "private": true, 5 | "scripts": { 6 | "dev": "next dev", 7 | "build": "next build", 8 | "start": "next start", 9 | "lint": "next lint" 10 | }, 11 | "dependencies": { 12 | "@types/node": "18.15.13", 13 | "@types/react": "18.0.37", 14 | "@types/react-dom": "18.0.11", 15 | "@upstash/qstash": "^0.3.6", 16 | "bunnygram": "workspace:*", 17 | "next": "13.3.0", 18 | "react": "18.2.0", 19 | "react-dom": "18.2.0", 20 | "typescript": "5.0.4", 21 | "zod": "^3.21.4" 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /packages/nextjs-example/src/app/example-route/route.ts: -------------------------------------------------------------------------------- 1 | import { sendEmail } from "@/tasks/send-email"; 2 | import { onReceive } from "bunnygram"; 3 | 4 | export const POST = onReceive({ 5 | config: sendEmail, 6 | job: async (props) => { 7 | console.log({ fromSend: props }); 8 | return { 9 | status: true, 10 | }; 11 | }, 12 | }); 13 | -------------------------------------------------------------------------------- /packages/nextjs-example/src/app/layout.tsx: -------------------------------------------------------------------------------- 1 | export const metadata = { 2 | title: 'Next.js', 3 | description: 'Generated by Next.js', 4 | } 5 | 6 | export default function RootLayout({ 7 | children, 8 | }: { 9 | children: React.ReactNode 10 | }) { 11 | return ( 12 | 13 | {children} 14 | 15 | ) 16 | } 17 | -------------------------------------------------------------------------------- /packages/nextjs-example/src/app/page.tsx: -------------------------------------------------------------------------------- 1 | "use client"; 2 | 3 | import { sendEmail } from "@/tasks/send-email"; 4 | import { send } from "bunnygram"; 5 | 6 | const Page = () => { 7 | const runJob = async () => { 8 | const resp = await send({ 9 | config: sendEmail, 10 | payload: { 11 | name: "sarim", 12 | }, 13 | }); 14 | console.log({ fromReceive: resp }); 15 | }; 16 | 17 | return ( 18 |
19 |
20 |
21 | );
22 | };
23 |
24 | export default Page;
25 |
--------------------------------------------------------------------------------
/packages/nextjs-example/src/tasks/send-email.ts:
--------------------------------------------------------------------------------
1 | import { BasicAdapter, QStashAdapter, makeConfig } from "bunnygram";
2 |
3 | interface JobPayload {
4 | name: string;
5 | }
6 |
7 | interface JobResponse {
8 | status: boolean;
9 | }
10 |
11 | export const sendEmail = makeConfig