PreviewCron SDK

Trigger & test your Vercel cron jobs locally or on preview deployments — with a simple UI.

Features

• Auto-reads vercel.json from your project
• Beautiful dashboard UI to test cron jobs
• Real-time execution status and duration tracking
• Authorization header support for protected endpoints
• Development-only (automatically disabled in production)
• Zero configuration for basic usage
• Vanilla CSS (no Tailwind required)
• TypeScript support

Quick start (no install)

The fastest way — run it in your project, no setup, no files to add:

npx previewcron

It reads vercel.json from the current directory, opens a dashboard in your browser, and lets you trigger each cron job against your local dev server. If a CRON_SECRET is set (env or .env.local), the Authorization header is pre-filled automatically.

Because the dashboard runs locally, it can hit localhost directly (no CORS, no SSRF restrictions like the hosted previewcron.dev).

npx previewcron [options]

  -p, --port <number>     Port for the dashboard (default: 4747)
  -b, --base-url <url>    Target app base URL (default: http://localhost:3000)
      --vercel-json <p>   Path to vercel.json (default: ./vercel.json)
      --no-open           Do not open the browser automatically
  -v, --version           Print version
  -h, --help              Show this help

Example — your dev server runs on port 4000:

npx previewcron --base-url http://localhost:4000

Prefer an in-app dashboard route instead? Install the package and follow the SDK setup below.

Installation

npm install previewcron --save-dev
# or
bun add -d previewcron
# or
yarn add -D previewcron

Quick Start

1. Create a page for the dashboard

You can place this anywhere in your Next.js app. Common locations:

// app/dev/cron/page.tsx
// OR app/admin/cron-test/page.tsx

export { default } from "previewcron/page";

2. Import the styles

Add the CSS import to your layout or page:

// app/dev/cron/layout.tsx (recommended)
import "previewcron/styles.css";

export default function Layout({ children }: { children: React.ReactNode }) {
  return children;
}

Or import directly in your page:

// app/dev/cron/page.tsx
import "previewcron/styles.css";
export { default } from "previewcron/page";

3. Make sure you have a vercel.json file

{
  "crons": [
    {
      "path": "/api/cron/cleanup",
      "schedule": "0 0 * * *"
    }
  ]
}

4. Start your dev server and visit the dashboard

npm run dev

Then navigate to the route you created (e.g., http://localhost:3000/dev/cron)

That's it! You'll see all your cron jobs listed and can test them with a single click.

Authorization Support

The dashboard includes an optional Authorization header input. This is useful for testing cron endpoints that require authentication:

1. Enter your authorization value in the "Authorization" field (e.g., Bearer YOUR_SECRET_TOKEN)
2. Click "Run" on any cron job
3. The Authorization header will be included in the request

Advanced Usage

Custom Base URL

If your dev server runs on a different port:

// app/dev/cron/page.tsx
import CronDevPage from "previewcron/page";

export default function Page() {
  return <CronDevPage baseUrl="http://localhost:4000" />;
}

Custom vercel.json Path

If your vercel.json is in a different location:

import CronDevPage from "previewcron/page";

export default function Page() {
  return <CronDevPage vercelJsonPath="./config/vercel.json" />;
}

Inline Configuration

Instead of reading from a file, you can pass the config directly:

import CronDevPage from "previewcron/page";

export default function Page() {
  return (
    <CronDevPage
      config={{
        crons: [
          {
            path: "/api/cron/test",
            schedule: "* * * * *",
          },
        ],
      }}
    />
  );
}

Using Individual Components

For more control, you can use the individual components:

"use client";

import { CronDashboard } from "previewcron/client";
import "previewcron/styles.css";
import type { VercelCron } from "previewcron";

export default function CustomCronPage() {
  const crons: VercelCron[] = [
    { path: "/api/cron/test", schedule: "0 0 * * *" },
  ];

  return <CronDashboard crons={crons} baseUrl="http://localhost:3000" />;
}

API Reference

CronDevPage (Default Export)

Server Component that reads vercel.json and renders the dashboard.

Props:

• vercelJsonPath?: string - Custom path to vercel.json file
• baseUrl?: string - Base URL for cron jobs (default: http://localhost:3000)
• config?: VercelConfig - Inline config instead of reading from file

CronDashboard (Client Component)

Client Component for rendering the dashboard.

Props:

• crons: VercelCron[] - Array of cron jobs
• baseUrl: string - Base URL for making requests

Server Utilities

import { readVercelJson } from 'previewcron/server';

const result = await readVercelJson({
  path: './vercel.json', // optional
  baseUrl: 'http://localhost:3000', // optional
  config: { crons: [...] }, // optional inline config
});

Shared Types

import type { VercelCron, VercelConfig, CronJobWithStatus } from "previewcron";

Utilities

import { parseCronSchedule } from "previewcron";

const readable = parseCronSchedule("0 0 * * *"); // "At 12:00 AM"

Security

This package is designed for development use only. The dashboard:

• Only works when NODE_ENV === 'development'
• Returns a 404-like page in production
• Does not include any authentication

Never expose the cron testing dashboard in production environments.

Styling

The package includes its own vanilla CSS stylesheet that works without Tailwind or any other CSS framework. The styles:

• Use CSS custom properties for theming
• Support light and dark mode (via prefers-color-scheme)
• Are scoped under .previewcron-root to avoid conflicts
• Use the JetBrains Mono font family

Import the styles in your layout or page:

import "previewcron/styles.css";

How It Works

1. The SDK reads your vercel.json file (server-side)
2. Extracts all cron job definitions
3. Renders a two-column dashboard UI (configuration on left, jobs on right)
4. When you click "Run", it makes a direct fetch to your local endpoint
5. Optionally includes an Authorization header if provided
6. Displays the response, status code, and execution time

Testing vs Production

• Local Development (SDK): Test cron jobs on localhost with this package
• Preview Deployments: Use previewcron.dev to test on Vercel preview URLs
• Production: Cron jobs run automatically on schedule via Vercel

Examples

Testing a cleanup cron

{
  "crons": [
    {
      "path": "/api/cron/cleanup",
      "schedule": "0 0 * * *"
    }
  ]
}

// app/api/cron/cleanup/route.ts
export async function GET() {
  // Your cleanup logic
  await cleanupOldData();

  return Response.json({ success: true, message: "Cleanup completed" });
}

Now you can test this endpoint instantly from the dashboard instead of waiting for the schedule or manually visiting the URL!

License

MIT

Author

Ludovic Gueth

Links

• GitHub
• Web App