# Crons

Runtime-managed recurring schedules

- Package: @bijectionhq/crons
- Category: Durable Functions
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/crons/tree/b9fa198de79e18be5b6400ad4090570f0591e986
- Upstream: https://github.com/convex/crons/tree/4ea5b4f133222c5125a7126cb9e42fa0a27a97b5
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/crons

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/crons.git
cd crons
git checkout b9fa198de79e18be5b6400ad4090570f0591e986
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Upstream package documentation

Recorded 2026-10-23. This describes @convex-dev/crons; check the Bijection adaptation separately.

This component extends Convex's built-in cron functionality by enabling dynamic registration and management of cron jobs at runtime. While Convex's native crons must be statically defined at deployment time, this component provides programmatic APIs to create, update, and delete scheduled jobs from within your functions. It supports both traditional cron expressions and simple millisecond intervals for flexible scheduling needs.

### Use cases

• **Dynamic content scheduling** - Register cleanup jobs, send reminder emails, or archive old data based on user actions or database events
• **Tenant-specific automation** - Create per-customer scheduled tasks like report generation, billing cycles, or data backups without hardcoding schedules
• **Self-managing workflows** - Build cron jobs that register follow-up tasks or delete themselves after completion, enabling complex multi-step automations
• **Runtime configuration** - Allow admins to configure maintenance windows, batch processing schedules, or monitoring intervals through your application UI
• **Event-driven scheduling** - Create temporary scheduled tasks in response to user signup, subscription changes, or other business events

### How it works

The component provides a `Crons` wrapper class that manages scheduled jobs through five core methods: `register()`, `get()`, `list()`, and `delete()`. Jobs can be scheduled using either cron expressions (supporting the standard unix cron format with optional seconds) or simple millisecond intervals.

After installing the component via `npm install @convex-dev/crons` and configuring it in `convex.config.ts`, you instantiate the wrapper with `new Crons(components.crons)`. The `register()` method accepts a schedule specification, target function reference, arguments object, and optional name for later retrieval.

Cron jobs are created transactionally within mutations, guaranteeing they exist after the creating transaction commits. This enables reliable patterns like self-deleting crons or workflows where job creation and subsequent operations must be atomic. For static job definitions similar to built-in crons, you can use idempotent registration in init scripts that check for existing jobs by name before creating them.

### Upstream README

This Convex component provides functionality for registering and managing cron
jobs at runtime. Convex comes with built-in support for cron jobs but they must
be statically defined at deployment time. This library allows for dynamic
registration of cron jobs at runtime.

```ts
// Register a cron to run once per day.
const daily = await crons.register(
  ctx,
  { kind: "cron", cronspec: "0 0 * * *" },
  internal.example.logStuff,
  { message: "daily cron" },
);

// Register a cron to run every hour.
const hourly = await crons.register(
  ctx,
  { kind: "interval", ms: 3600000 },
  internal.example.logStuff,
  { message: "hourly cron" },
);
```

It supports intervals in milliseconds as well as cron schedules with the same
format as the unix `cron` command:

```
 *  *  *  *  *  *
 ┬  ┬  ┬  ┬  ┬  ┬
 │  │  │  │  │  |
 │  │  │  │  │  └── day of week (0 - 7, 1L - 7L) (0 or 7 is Sun)
 │  │  │  │  └───── month (1 - 12)
 │  │  │  └──────── day of month (1 - 31, L)
 │  │  └─────────── hour (0 - 23)
 │  └────────────── minute (0 - 59)
 └───────────────── second (0 - 59, optional)
```

### Design

The design of this component is based on the Cronvex demo app that's described
in [this Stack post](https://stack.convex.dev/cron-jobs).

## Pre-requisite: Convex

You'll need an existing Convex project to use the component. Convex is a hosted
backend platform, including a database, serverless functions, and a ton more you
can learn about [here](https://docs.convex.dev/get-started).

Run `npm create convex` or follow any of the
[quickstarts](https://docs.convex.dev/home) to set one up.

## Installation

Install the component package:

```ts
npm install @convex-dev/crons
```

Create a `convex.config.ts` file in your app's `convex/` folder and install the
component by calling `use`:

```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import crons from "@convex-dev/crons/convex.config.js";

const app = defineApp();
app.use(crons);

export default app;
```

## Usage

A `Crons` wrapper can be instantiated within your Convex code as:

```ts
import { components } from "./_generated/api";
import { Crons } from "@convex-dev/crons";

const crons = new Crons(components.crons);
```

The `Crons` wrapper class provides the following methods:

- `register(ctx, schedule, fn, args, name?)`: Registers a new cron job.
- `get(ctx, { name | id })`: Gets a cron job by name or ID.
- `list(ctx)`: Lists all cron jobs.
- `delete(ctx, { name | id })`: Deletes a cron job by name or ID.

Example usage:

```ts
import { v } from "convex/values";
import { internalMutation } from "./_generated/server";
import { internal } from "./_generated/api";

// Dummy function that we're going to schedule.
export const logStuff = internalMutation({
  args: {
    message: v.string(),
  },
  handler: async (_ctx, args) => {
    console.log(args.message);
  },
});

// Run a bunch of cron operations as a test. Note that this function runs as a
// transaction and cleans up after itself so you won't actually see these crons
// showing up in the database while it's in progress.
export const doSomeStuff = internalMutation({
  handler: async (ctx) => {
    // Register some crons.
    const namedCronId = await crons.register(
      ctx,
      { kind: "interval", ms: 3600000 },
      internal.example.logStuff,
      { message: "Hourly cron test" },
      "hourly-test",
    );
    console.log("Registered new cron job with ID:", namedCronId);
    const unnamedCronId = await crons.register(
      ctx,
      { kind: "cron", cronspec: "0 * * * *" },
      internal.example.logStuff,
      { message: "Minutely cron test" },
    );
    console.log("Registered new cron job with ID:", unnamedCronId);

    // Get the cron job by name.
    const cronByName = await crons.get(ctx, { name: "hourly-test" });
    console.log("Retrieved cron job by name:", cronByName);

    // Get the cron job by ID.
    const cronById = await crons.get(ctx, { id: unnamedCronId });
    console.log("Retrieved cron job by ID:", cronById);

    // List all cron jobs.
    const allCrons = await crons.list(ctx);
    console.log("All cron jobs:", allCrons);

    // Delete the cron jobs.
    await crons.delete(ctx, { name: "hourly-test" });
    console.log("Deleted cron job by name:", "hourly-test");
    await crons.delete(ctx, { id: unnamedCronId });
    console.log("Deleted cron job by ID:", unnamedCronId);

    // Verify deletion.
    const deletedCronByName = await crons.get(ctx, { name: "hourly-test" });
    console.log("Deleted cron job (should be null):", deletedCronByName);
    const deletedCronById = await crons.get(ctx, { id: unnamedCronId });
    console.log("Deleted cron job (should be null):", deletedCronById);
  },
});
```

If you'd like to statically define cronjobs like in the built-in `crons.ts`
Convex feature you can do so via an init script that idempotently registers a
cron with a given name. e.g., in an `init.ts` file that gets run on every deploy
via `convex dev --run init`.

```ts
// Register a daily cron job. This could be called from an init script to make
// sure it's always registered, like the built-in crons in Convex.
export const registerDailyCron = internalMutation({
  handler: async (ctx) => {
    if ((await crons.get(ctx, { name: "daily" })) === null) {
      await crons.register(
        ctx,
        { kind: "cron", cronspec: "0 0 * * *" },
        internal.example.logStuff,
        {
          message: "daily cron",
        },
        "daily",
      );
    }
  },
});
```

Crons are created transactionally and will be guaranteed to exist after the
mutation that creates them has run. It's thus possible to write workflows like
the following that schedules a cron and then deletes itself as soon as it runs,
without any additional error handling about the cron not existing.

```ts
// This will schedule a cron job to run every 10 seconds but then delete itself
// the first time it runs.
export const selfDeletingCron = internalMutation({
  handler: async (ctx) => {
    const cronId = await crons.register(
      ctx,
      { kind: "interval", ms: 10000 },
      internal.example.deleteSelf,
      { name: "self-deleting-cron" },
      "self-deleting-cron",
    );

    console.log("Registered self-deleting cron job with ID:", cronId);
  },
});

// Worker function that deletes a cron job.
export const deleteSelf = internalMutation({
  args: { name: v.string() },
  handler: async (ctx, { name }) => {
    console.log("Self-deleting cron job running. Name:", name);
    await crons.delete(ctx, { name });
    console.log("Self-deleting cron job has been deleted. Name:", name);
  },
});
```