The Cron API registers scheduled background tasks for your applet. Prefer defineCron, which supports a fixed interval, a 5-field Unix cron expression, and per-row schedules driven by entity data. The raw ctx.sdk.cron bridge is an escape hatch.

Scope required: cron:register

Usage

defineCron takes an id plus one scheduling form and a run handler:

import { defineCron } from "@rightplace/applet-sdk/v2";

// fixed interval - register once on mount
export const refresh = defineCron({
  id: "rss.refreshAll",
  every: "30m",                                  // sugar for "*/30 * * * *"
  async run(ctx) { /* ... */ },
});

// or 5-field Unix cron expression
export const nightly = defineCron({
  id: "rss.nightly",
  schedule: "0 3 * * *",
  async run(ctx) { /* ... */ },
});

// per-row - SDK auto-registers/unregisters as entity rows insert/delete
export const refreshOne = defineCron({
  id: "rss.refreshFeed",
  perRow: { entity: "feed", schedule: row => `*/${row.fetchIntervalSecs}s` },
  async run(ctx, { row: feed }) { /* ... */ },
});

Interval sugar

The every field accepts a short interval string:

Format	Example	Meaning
Ns	"30s"	Every N seconds
Nm	"30m"	Every N minutes
Nh	"1h"	Every N hours
Nd	"1d"	Every N days

Sub-minute intervals (Ns) error at build time. Use schedule (a 5-field cron expression) when you need finer control than every provides.

Raw bridge

When you need the scheduler directly, use ctx.sdk.cron inside a method’s run. Lint prefers defineCron.

await ctx.sdk.cron.register({
  id: "rss.refresh",
  schedule: "*/30 * * * *",
});
ctx.sdk.cron.onTick("rss.refresh", async () => {
  /* ... */
});
await ctx.sdk.cron.unregister("rss.refresh");

Manifest Configuration

Declare the scope in applet.json:

{
  "scopes": ["cron:register"]
}

Notes

• defineCron is the preferred, lint-clean path; ctx.sdk.cron is the raw escape hatch.
• Pick exactly one scheduling form per task: every (fixed interval sugar), schedule (5-field cron), or perRow (entity-driven).
• perRow registers and unregisters a task automatically as rows in the named entity insert and delete; the run handler receives the row.
• every sub-minute values (Ns) are rejected at build. For sub-minute work use a schedule cron expression.
• Both forms require the cron:register scope in applet.json::scopes[].