Crons
Runtime-managed recurring schedules
git clone https://github.com/bijectionhq/crons.git
cd crons
git checkout b9fa198de79e18be5b6400ad4090570f0591e986Bijection repository access is required. Request access.
Description
Runtime-managed recurring schedules
Explore the package README for API concepts, configuration, and examples. Check the Bijection source for adaptation-specific setup.
Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.
Getting started
- Get the source at the revision above and read its package documentation.
- Check the required Bijection SDK version, dependencies, and external service credentials.
- Follow the package setup instructions and the guide to using components.
- Exercise the component in your deployment according to your project’s verification rules.
Open source
Maintained source: bijectionhq/crons. Based on convex/crons. License: Apache-2.0. Consult the repository for license terms, notices, and contributor attribution.
From the upstream publisher
Convex component for scheduling periodic jobs.
Explore the demo ↗Upstream overview
From the upstream package documentation.
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
From the upstream package documentation.
- 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
From the upstream package documentation.
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.
Use with agents and CLI
Give your coding agent the component’s source identity and setup guidance.
Help me integrate Crons with Bijection.
Read: https://bijection.com/components/crons/SKILL.md
Check SDK compatibility and dependency availability.
Follow this project's execution and verification rules.Upstream README.md
View repository ↗Documentation from convex/crons, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.
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.
// 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.
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.
Run npm create convex or follow any of the
quickstarts to set one up.
Installation
Install the component package:
npm install @convex-dev/crons
Create a convex.config.ts file in your app's convex/ folder and install the
component by calling use:
// 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:
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:
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.
// 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.
// 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);
},
});