JobScheduler
Schedule one-time and recurring cron jobs
JobList
View and manage all scheduled jobs
CronBuilder
Visual cron expression builder
Installation
@sylphx/platform-sdk/react.JobScheduler
A comprehensive form component for scheduling background jobs. Supports one-time jobs, delayed jobs, and recurring cron schedules with a clean, intuitive interface.
Basic Usage
import { JobScheduler } from '@sylphx/platform-sdk/react'
export default function NewJobPage() {
return (
<JobScheduler
onSchedule={(job) => {
console.log('Job scheduled:', job.id)
}}
/>
)
}Props
| Property | Type | Description |
|---|---|---|
onSchedulerequired | (job: Job) => void | Callback when job is successfully scheduled |
defaultUrl | string | Pre-fill the job URL endpoint |
defaultPayload | object | Pre-fill the job payload/body |
defaultMode | "immediate" | "delayed" | "cron"= "immediate" | Initial scheduling mode |
allowedModes | ScheduleMode[] | Limit available scheduling modes |
endpoints | Endpoint[] | Predefined endpoints for dropdown selection |
showRetryConfig | boolean= true | Show retry configuration options |
showTimeoutConfig | boolean= true | Show timeout configuration |
showHeaders | boolean= false | Allow custom headers |
maxRetries | number= 10 | Maximum allowed retry attempts |
maxTimeout | number= 900 | Maximum timeout in seconds |
onError | (error: Error) => void | Callback when scheduling fails |
onCancel | () => void | Callback when user cancels |
submitLabel | string= "Schedule Job" | Custom submit button text |
loading | boolean= false | Show loading state |
disabled | boolean= false | Disable the form |
className | string | Additional CSS classes |
Advanced Configuration
import { JobScheduler, type Endpoint } from '@sylphx/platform-sdk/react'
const endpoints: Endpoint[] = [
{
label: 'Send Email',
url: '/api/jobs/send-email',
description: 'Send transactional emails',
payloadSchema: {
to: { type: 'string', required: true },
template: { type: 'string', required: true },
data: { type: 'object' },
},
},
{
label: 'Generate Report',
url: '/api/jobs/generate-report',
description: 'Generate PDF reports',
payloadSchema: {
reportType: { type: 'string', required: true },
dateRange: { type: 'object' },
},
},
{
label: 'Process Upload',
url: '/api/jobs/process-upload',
description: 'Process uploaded files',
},
]
<JobScheduler
endpoints={endpoints}
onSchedule={(job) => console.log('Scheduled:', job)}
/>URL Validation
JobList
A data table component for viewing, filtering, and managing scheduled jobs. Supports pagination, filtering by status, and bulk actions.
Basic Usage
import { JobList } from '@sylphx/platform-sdk/react'
export default function JobsPage() {
return (
<JobList
title="Scheduled Jobs"
onJobClick={(job) => router.push(`/admin/jobs/${job.id}`)}
/>
)
}Props
| Property | Type | Description |
|---|---|---|
title | string= "Jobs" | Title displayed above the list |
status | JobStatus | JobStatus[] | Filter by job status |
type | "one-time" | "cron" | Filter by job type |
limit | number= 25 | Jobs per page |
showFilters | boolean= true | Show filter controls |
showSearch | boolean= true | Show search input |
showPagination | boolean= true | Show pagination controls |
showActions | boolean= true | Show action buttons (pause, cancel, retry) |
selectable | boolean= false | Enable row selection for bulk actions |
autoRefresh | boolean= false | Auto-refresh list every 10 seconds |
refreshInterval | number= 10000 | Auto-refresh interval in ms |
columns | Column[] | Custom columns to display |
onJobClick | (job: Job) => void | Callback when job row is clicked |
onPause | (job: Job) => void | Callback when job is paused |
onResume | (job: Job) => void | Callback when job is resumed |
onCancel | (job: Job) => void | Callback when job is cancelled |
onRetry | (job: Job) => void | Callback when job is retried |
onBulkAction | (action: string, jobs: Job[]) => void | Callback for bulk actions |
emptyMessage | string= "No jobs found" | Message when no jobs found |
loading | boolean= false | Show loading state |
className | string | Additional CSS classes |
JobStatus Type
type JobStatus =
| 'pending' // Job is queued, waiting to run
| 'running' // Job is currently executing
| 'completed' // Job finished successfully
| 'failed' // Job failed after all retries
| 'cancelled' // Job was manually cancelled
| 'paused' // Recurring job is pausedAdvanced Usage
import { JobList } from '@sylphx/platform-sdk/react'
// Show only failed jobs
<JobList
title="Failed Jobs"
status="failed"
showFilters={false}
/>
// Show active jobs (pending or running)
<JobList
title="Active Jobs"
status={['pending', 'running']}
autoRefresh={true}
refreshInterval={5000}
/>
// Show only cron jobs
<JobList
title="Recurring Jobs"
type="cron"
showActions={true}
/>Real-time Updates
autoRefresh for dashboards that need to show live job status. The component will poll for updates at the specified interval.CronBuilder
A visual cron expression builder that makes it easy to create complex schedules without memorizing cron syntax. Includes a human-readable preview and next run times.
Basic Usage
import { CronBuilder } from '@sylphx/platform-sdk/react'
export function SchedulePicker() {
const [cron, setCron] = useState('0 9 * * *')
return (
<CronBuilder
value={cron}
onChange={setCron}
/>
)
}Props
| Property | Type | Description |
|---|---|---|
valuerequired | string | Current cron expression |
onChangerequired | (cron: string) => void | Callback when expression changes |
mode | "simple" | "advanced"= "simple" | UI mode - simple shows presets, advanced shows full editor |
showPreview | boolean= true | Show human-readable description |
showNextRuns | boolean= true | Show next scheduled run times |
nextRunCount | number= 5 | Number of next runs to display |
timezone | string= browser timezone | Timezone for display |
showTimezone | boolean= true | Show timezone selector |
presets | CronPreset[] | Custom preset options |
minInterval | number= 1 | Minimum interval in minutes |
disabledFields | CronField[] | Disable specific fields (minute, hour, etc.) |
onError | (error: string) => void | Callback for validation errors |
compact | boolean= false | Use compact layout |
disabled | boolean= false | Disable the builder |
className | string | Additional CSS classes |
CronPreset Type
interface CronPreset {
label: string // Display name (e.g., "Every hour")
value: string // Cron expression (e.g., "0 * * * *")
description?: string // Optional description
icon?: ReactNode // Optional icon
}Built-in Presets
| Preset | Expression | Description |
|---|---|---|
| Every minute | * * * * * | Runs every minute |
| Every hour | 0 * * * * | Runs at the start of every hour |
| Daily at midnight | 0 0 * * * | Runs every day at 00:00 |
| Weekdays at 9am | 0 9 * * 1-5 | Runs Monday-Friday at 9:00 AM |
| Weekly on Sunday | 0 0 * * 0 | Runs every Sunday at midnight |
| Monthly | 0 0 1 * * | Runs on the 1st of every month |
Examples
import { CronBuilder } from '@sylphx/platform-sdk/react'
// Simple mode with presets (default)
<CronBuilder
value={cron}
onChange={setCron}
mode="simple"
showPreview={true}
showNextRuns={true}
/>Minimum Interval
minInterval to prevent users from scheduling jobs too frequently. This helps avoid overwhelming your job handlers with excessive requests.Complete Example
Here is a complete example combining all job components into a job management interface:
'use client'
import { useState } from 'react'
import {
JobScheduler,
JobList,
CronBuilder,
} from '@sylphx/platform-sdk/react'
import { platform } from '@/lib/platform'
import { Plus, Calendar, List, Clock } from 'lucide-react'
export default function JobsManagementPage() {
const [view, setView] = useState<'list' | 'schedule'>('list')
const [cronValue, setCronValue] = useState('0 9 * * *')
const handleSchedule = async (job) => {
await platform.jobs.schedule(job)
toast.success('Job scheduled successfully!')
setView('list') // Return to list view
}
const handleCancel = async (job) => {
await platform.jobs.cancel(job.id)
toast.success('Job cancelled')
}
const handleRetry = async (job) => {
await platform.jobs.retry(job.id)
toast.success('Job queued for retry')
}
return (
<div className="max-w-6xl mx-auto p-6 space-y-8">
<div className="flex items-center justify-between">
<h1 className="text-3xl font-bold">Background Jobs</h1>
<div className="flex gap-2">
<button
onClick={() => setView('list')}
className={`px-4 py-2 rounded-lg flex items-center gap-2 ${
view === 'list'
? 'bg-primary text-primary-foreground'
: 'bg-muted'
}`}
>
<List className="w-4 h-4" />
View Jobs
</button>
<button
onClick={() => setView('schedule')}
className={`px-4 py-2 rounded-lg flex items-center gap-2 ${
view === 'schedule'
? 'bg-primary text-primary-foreground'
: 'bg-muted'
}`}
>
<Plus className="w-4 h-4" />
New Job
</button>
</div>
</div>
{view === 'list' ? (
<JobList
title="All Jobs"
showFilters={true}
showSearch={true}
showActions={true}
autoRefresh={true}
refreshInterval={10000}
onCancel={handleCancel}
onRetry={handleRetry}
onJobClick={(job) => router.push(`/admin/jobs/${job.id}`)}
/>
) : (
<div className="grid grid-cols-2 gap-8">
<div>
<h2 className="text-xl font-semibold mb-4 flex items-center gap-2">
<Clock className="w-5 h-5" />
Schedule a Job
</h2>
<JobScheduler
onSchedule={handleSchedule}
onCancel={() => setView('list')}
showRetryConfig={true}
showTimeoutConfig={true}
endpoints={[
{ label: 'Send Email', url: '/api/jobs/send-email' },
{ label: 'Generate Report', url: '/api/jobs/report' },
{ label: 'Sync Data', url: '/api/jobs/sync' },
]}
/>
</div>
<div>
<h2 className="text-xl font-semibold mb-4 flex items-center gap-2">
<Calendar className="w-5 h-5" />
Cron Schedule Builder
</h2>
<CronBuilder
value={cronValue}
onChange={setCronValue}
mode="simple"
showPreview={true}
showNextRuns={true}
showTimezone={true}
/>
</div>
</div>
)}
</div>
)
}Theming
All job components inherit theming from the SylphxProvider:
import { SylphxProvider, JobList, JobScheduler } from '@sylphx/platform-sdk/react'
// Global theming via provider
<SylphxProvider
theme={{
colorPrimary: '#6366f1',
colorSuccess: '#10b981',
colorWarning: '#f59e0b',
colorDanger: '#ef4444',
borderRadius: '0.75rem',
}}
>
<JobList title="Jobs" />
<JobScheduler onSchedule={handleSchedule} />
</SylphxProvider>
// Individual component styling
<JobList
title="Jobs"
className="border-2 border-primary/20 rounded-2xl"
/>
<CronBuilder
value={cron}
onChange={setCron}
className="bg-muted p-4 rounded-xl"
/>Server Components
'use client' at the top of your page.