Next.js

Set up Pingback in your Next.js app with the @usepingback/next adapter.

Installation

npm install @usepingback/next

CLI

Use npx pingback init to scaffold your project with the recommended config, route handler, and file structure:

npx pingback init

For local development, use npx pingback dev to create a tunnel so the platform can reach your local server:

npx pingback dev

Configuration

Create pingback.config.ts in your project root:

import { defineConfig } from "@usepingback/next";

export default defineConfig({
  apiKey: process.env.PINGBACK_API_KEY,
});

Next.js Plugin

Wrap your Next.js config with withPingback(). At build time, it scans your project for cron() and task() calls, collects their metadata, and registers them with the Pingback platform:

import { withPingback } from "@usepingback/next";

export default withPingback({
  // your existing Next.js config
});

Route Handler

Create app/api/pingback/route.ts to receive execution requests from the platform:

import { createRouteHandler } from "@usepingback/next/handler";

export const POST = createRouteHandler();

The handler validates the HMAC signature using your PINGBACK_CRON_SECRET, looks up the requested function, executes it, and returns the result with logs.

Define Functions

Create your cron and task functions anywhere in your project. They are automatically discovered at build time:

import { cron, task } from "@usepingback/next";

export const sendEmails = cron(
  "send-emails",
  "*/15 * * * *",
  async (ctx) => {
    const pending = await getPendingEmails();
    for (const email of pending) {
      await ctx.task("send-email", { id: email.id });
    }
    ctx.log(`Dispatched ${pending.length} emails`);
  },
  { retries: 3, timeout: "60s" }
);

export const sendEmail = task(
  "send-email",
  async (ctx, { id }: { id: string }) => {
    const email = await getEmail(id);
    await deliver(email);
  },
  { retries: 2, timeout: "15s" }
);

Environment Variables

Add these to your .env.local:

PINGBACK_API_KEY=pb_live_your_api_key_here
PINGBACK_CRON_SECRET=your_cron_secret_here

Deploy

Deploy your app. Pingback discovers your functions at build time, registers them with the platform, and starts scheduling. Monitor executions in the dashboard.

Local Development

Use npx pingback dev [port] to test your cron jobs and tasks locally against the production Pingback platform. The CLI creates a secure tunnel to your local Next.js dev server so the platform can invoke your route handler:

# Start your Next.js dev server, then in another terminal:
npx pingback dev 3000

Executions triggered from the dashboard or by schedule will be routed to your local machine, letting you debug with full access to local logs and breakpoints.