Cron Syntax
5-field expression format
Timezone Support
UTC or local timezone
Visual Builder
Build expressions visually
Expression Testing
Preview next run times
Cron Expression Syntax
A cron expression consists of 5 fields separated by spaces. Each field represents a unit of time and determines when the task should run.
┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *Field Definitions
| Property | Type | Description |
|---|---|---|
Minute | 0-59 | Minute of the hour (0 = top of hour) |
Hour | 0-23 | Hour of the day (0 = midnight, 23 = 11pm) |
Day of Month | 1-31 | Day of the month (1 = first day) |
Month | 1-12 | Month of the year (1 = January, 12 = December) |
Day of Week | 0-6 | Day of the week (0 = Sunday, 6 = Saturday) |
Special Characters
Use special characters to create flexible scheduling patterns:
| Property | Type | Description |
|---|---|---|
* | wildcard | Matches any value (e.g., every minute, every hour) |
, | list | Specifies multiple values (e.g., 1,3,5 = Mon, Wed, Fri) |
- | range | Specifies a range (e.g., 1-5 = Monday through Friday) |
/ | step | Specifies increments (e.g., */15 = every 15 minutes) |
// Examples of special characters
// Asterisk (*) - every value
* * * * * // Every minute
// Comma (,) - multiple specific values
0 9,12,18 * * * // At 9am, 12pm, and 6pm
// Hyphen (-) - range of values
0 9 * * 1-5 // Weekdays at 9am (Monday through Friday)
// Slash (/) - step values
*/15 * * * * // Every 15 minutes
0 */4 * * * // Every 4 hoursCommon Cron Patterns
Reference these commonly used patterns for typical scheduling needs:
| Property | Type | Description |
|---|---|---|
* * * * * | pattern | Every minute |
*/5 * * * * | pattern | Every 5 minutes |
*/15 * * * * | pattern | Every 15 minutes |
0 * * * * | pattern | Every hour (at minute 0) |
0 */2 * * * | pattern | Every 2 hours |
0 0 * * * | pattern | Daily at midnight |
0 9 * * * | pattern | Daily at 9:00 AM |
0 9 * * 1-5 | pattern | Weekdays at 9:00 AM |
0 0 * * 0 | pattern | Weekly on Sunday at midnight |
0 6 * * 1 | pattern | Weekly on Monday at 6:00 AM |
0 0 1 * * | pattern | Monthly on the 1st at midnight |
0 0 1 1 * | pattern | Yearly on January 1st at midnight |
Pattern Builder
Use the CronBuilder component to visually create cron expressions without memorizing the syntax.
Timezone Handling
By default, all cron expressions are evaluated in UTC. You can specify a timezone to run tasks in local time.
UTC timezone
import { createCron } from '@sylphx/sdk/tasks'
const config = {
secretKey: process.env.SYLPHX_SECRET_KEY!,
ref: process.env.SYLPHX_PROJECT_REF!,
}
// Runs at 9am UTC every day
await createCron(config, {
name: 'daily-report',
cron: '0 9 * * *',
callbackUrl: 'https://myapp.com/api/tasks',
// No timezone specified = UTC
})Daylight Saving Time
When using local timezones, be aware of DST transitions. Tasks scheduled during the "skipped" hour (when clocks spring forward) will not run. Tasks during the "repeated" hour (when clocks fall back) will run once.
Scheduling via SDK
Create recurring tasks programmatically using the Tasks SDK.
lib/scheduled-tasks.ts
import { createCron, deleteCron, pauseCron, resumeCron } from '@sylphx/sdk/tasks'
const config = {
secretKey: process.env.SYLPHX_SECRET_KEY!,
ref: process.env.SYLPHX_PROJECT_REF!,
}
// Schedule a daily report
export async function scheduleDailyReport(orgId: string) {
return createCron(config, {
name: `daily-report-${orgId}`,
cron: '0 6 * * *', // 6am UTC daily
callbackUrl: 'https://myapp.com/api/tasks',
payload: {
taskName: 'generate-report',
orgId,
type: 'daily',
},
retries: 3,
})
}
// Schedule hourly cleanup
export async function scheduleCleanup() {
return createCron(config, {
name: 'hourly-cleanup',
cron: '0 * * * *', // Every hour
callbackUrl: 'https://myapp.com/api/tasks',
payload: { taskName: 'cleanup' },
})
}
// Schedule weekly digest on Mondays
export async function scheduleWeeklyDigest(userId: string, timezone: string) {
return createCron(config, {
name: `weekly-digest-${userId}`,
cron: '0 9 * * 1', // Monday 9am
timezone,
callbackUrl: 'https://myapp.com/api/tasks',
payload: { taskName: 'weekly-digest', userId },
})
}Cron Payload
Use the
payload field to pass data to your task handler on each cron trigger. Include taskName to route cron events to the right task in your serve() handler.Managing Cron Schedules
Pause, resume, and delete cron schedules through the SDK.
Control crons
import { pauseCron, resumeCron, deleteCron } from '@sylphx/sdk/tasks'
const config = {
secretKey: process.env.SYLPHX_SECRET_KEY!,
ref: process.env.SYLPHX_PROJECT_REF!,
}
// Pause a cron schedule (stops future runs)
await pauseCron(config, scheduleId)
// Resume a paused cron schedule
await resumeCron(config, scheduleId)
// Delete a cron schedule permanently
await deleteCron(config, scheduleId)Console Features
The Sylphx console provides a visual interface for managing cron tasks:
Visual Schedule
See upcoming runs in a calendar view with timezone conversion
Run History
View execution history, duration, and success/failure rates
Manual Trigger
Trigger a cron task manually for testing without waiting for schedule
Quick Actions
Pause, resume, edit, or delete cron schedules directly from the dashboard
Best Practices
Use Descriptive Names
Always use meaningful names for your cron schedules to make them easier to identify and manage in the console.
Avoid Minute 0
Many systems schedule tasks at exactly :00 minutes. Consider using an offset (e.g.,
5 * * * *) to distribute load.Overlapping Runs
If a task takes longer than the interval between runs, the next run will be skipped. Ensure your timeout is shorter than your interval, or design tasks to handle concurrent execution.
Idempotency
Design your task handlers to be idempotent. If a task runs twice due to retries or scheduler issues, it should produce the same result.