Cron Jobs Module Recipe

The Cron Jobs module is the admin surface for the scheduler of your DaaS backend. A job is a JavaScript snippet the server runs on a schedule (a cron expression read in a timezone) or on demand. A run is one execution of a job: its outcome, what started it, how long it took, and its console output.

The module gives you two screens:

• CronJobsManager — the /cron page. A Jobs tab lists the jobs: search by name, schedule or description, refresh, pagination, and a row menu with Edit, Run Now, Activate or Deactivate, Clone and Delete. A History tab lists the runs of every job.
• CronJobDetail — the /cron/[id] editor: the job’s code beside its settings (name, description, schedule, timezone, timeout, memory limit, and status for a stored job), with Run Now, Activate or Deactivate and Save in the header. A second tab holds the run history of that job.

A row of either history opens the run log: the outcome, the trigger, the time, the duration, the error, and the console output line by line.

The pieces

Install

buildpad add cron-routes

buildpad add cron-management

NEXT_PUBLIC_BUILDPAD_DAAS_URL=https://your-daas.example.com

The routes

Two files give you the whole module:

app/[lang]/(authenticated)/
└── cron/
    ├── page.tsx            # /cron       — CronJobsManager
    └── [id]/page.tsx       # /cron/[id]  — CronJobDetail (use /cron/new to create)

The components do not navigate. Each page passes router callbacks, so your router (and its locale prefix) decides where a click goes.

"use client";
 
import React from 'react';
import { useLocaleRouter } from '@/lib/i18n/navigation';
import { CronJobsManager } from '@/components/ui/cron-management';
 
export default function CronJobsPage() {
  const router = useLocaleRouter();
 
  return (
    <CronJobsManager
      onJobClick={(job) => router.push(`/cron/${job.id}`)}
      onCreateJob={() => router.push('/cron/new')}
    />
  );
}

"use client";
 
import React, { use } from 'react';
import { useLocaleRouter } from '@/lib/i18n/navigation';
import { CronJobDetail } from '@/components/ui/cron-management';
 
export default function CronJobDetailPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = use(params);
  const router = useLocaleRouter();
 
  return (
    <CronJobDetail
      id={id}
      onBack={() => router.push('/cron')}
      onCreated={(job) => router.push(`/cron/${job.id}`)}
    />
  );
}

Component props

Every component also takes translations, a partial override of the cron dictionary namespace for that one instance.

CronJobsManager

CronJobDetail

CronRunsTable

Use it on its own to show runs on another page.

import { CronRunsTable } from '@/components/ui/cron-management';
 
<CronRunsTable jobId={job.id} pageSize={25} />

CronRunLogModal

CronRunsTable renders it. Use it directly only when you list runs yourself.

The badges

Each also takes size (a Mantine size) and data-testid.

The editor

• A new job starts with the schedule 0 9 * * 1-5, the timezone UTC, a timeout of 10000 ms, a memory limit of 64 MB, and the status Inactive. The Status field and the History tab appear once the job is stored.
• The name, the schedule and the code are required. Whether the schedule is a valid expression and whether the code compiles is the server’s to say: a refused save shows the server’s sentence.
• Save is disabled while there is nothing to save. A save of an existing job sends only the fields that changed.
• Run Now and Activate are disabled while the form has unsaved changes. Save first. Deactivate is not: it stops the job at once, and the unsaved changes stay in the form.
• Run Now is answered when the run has ended. The editor then opens the History tab and loads it. A job that was already running is not started again, and the notification says so.
• Timeout and Memory Limit take whole numbers only. An emptied field falls back to its default when it loses focus.
• A stored timezone that is not one of the options is added as an option of its own, and is kept as it is stored.

A job can be answered without some of its fields, when the user’s read grant on daas_cron_jobs leaves them out. Those fields are shown read-only and are never sent. When the code is withheld, the editor shows a notice in place of the code editor. It does not draw an empty editor.

The code editor

The built-in code editor is InputCode: a monospace textarea with line numbers. It has no syntax highlighting, and the module adds no editor library to your app.

To use your own editor, pass renderCodeEditor. It receives a CronCodeEditorProps object:

This example uses CodeMirror. The two packages it imports are not part of the module; install them in your app (pnpm add @uiw/react-codemirror @codemirror/lang-javascript).

"use client";
 
import React, { useMemo } from 'react';
import CodeMirror, { EditorView } from '@uiw/react-codemirror';
import { javascript } from '@codemirror/lang-javascript';
import type { CronCodeEditorProps } from '@/components/ui/cron-management';
 
export function HighlightedCronEditor({
  value,
  onChange,
  readOnly,
  minHeight,
  placeholder,
  id,
  'aria-labelledby': labelledBy,
  'aria-describedby': describedBy,
}: CronCodeEditorProps) {
  // The label and the description belong on the element that takes the text
  const extensions = useMemo(
    () => [
      javascript(),
      EditorView.contentAttributes.of({
        id,
        'aria-labelledby': labelledBy,
        'aria-describedby': describedBy,
      }),
    ],
    [id, labelledBy, describedBy],
  );
 
  return (
    <CodeMirror
      value={value}
      onChange={onChange}
      readOnly={readOnly}
      minHeight={`${minHeight}px`}
      placeholder={placeholder}
      extensions={extensions}
    />
  );
}

<CronJobDetail
  id={id}
  onBack={() => router.push('/cron')}
  onCreated={(job) => router.push(`/cron/${job.id}`)}
  renderCodeEditor={(props) => <HighlightedCronEditor {...props} />}
/>

The slot is not called when the code is withheld from the user.

defaultCode and codeHelp go with the slot. What the services object gives a job differs per backend. The default code and the default notice name only what both backends give. A host that knows its backend can start a new job with a better example, and say in the notice what a job can call.

The data layer

The screens are thin. The work is in two hooks that you can use anywhere under DaaSProvider.

import { useCronJobs, DaaSRequestError } from '@/lib/buildpad/hooks';
 
const { fetchJobs, runJob } = useCronJobs();
 
const { items, total, totalPages } = await fetchJobs({ search: 'report', status: 'active', page: 1, limit: 25 });

Each hook returns loading, error (the last failure’s message), errorInfo (the same failure as a DaaSRequestError), and its methods:

fetchJobs takes { page?, limit?, search?, status? } (defaults: page 1, 25 jobs) and resolves to a CronListResult<CronJobRecord>:

interface CronListResult<T> {
  items: T[];         // rows of this page
  total: number;      // rows matching the request across all pages
  totalPages: number; // at least 1
  page: number;       // page that was served
  limit: number;      // page size that was served
}

The two run methods take { page?, limit?, offset? } (default: 50 runs) and resolve to the same shape with an offset.

Three details matter when you call the hooks yourself:

• On a CronJobRecord only id and name are certain. A field the caller’s grant withholds is absent, code above all. An absent field is not an empty value: do not show a default in its place, and do not send one back.
• runJob resolves when the run has ended, to { historyId, skipped, message }. skipped is true when the job was already running and nothing ran. A run whose code failed still resolves; its outcome is the status of the history row.
• loading is true while any request of that hook instance is in flight, a run included. Keep a pending flag per action where that matters.

Every method rejects with a DaaSRequestError. Branch on its kind: notFound, forbidden, mfaRequired, unauthenticated, invalid (a schedule that is not a cron expression, code that does not compile — the message is the server’s sentence) or failure. See Typed errors for the fields. A failed load never resolves to an empty list, and a get never resolves without a record.

Form logic

The functions the editor is built on are pure and live in @/lib/buildpad/utils: cronJobToForm, withheldCronJobFields, changedCronJobFields, cronJobInputFromForm, findCronJobFormProblem, cronTimezoneOptions, displayCronTimezone, normalizeCronTimeoutMs, normalizeCronMemoryLimitMb and parseCronLogLine, with the constants CRON_FORM_DEFAULTS, CRON_TIMEZONE_OPTIONS, CRON_NUMBER_INPUTS and DEFAULT_CRON_CODE. Use them when you write a custom editor, so your saves send only what the user changed.

Permissions

Every check uses one collection: daas_cron_jobs, exported from @/lib/buildpad/types as CRON_JOBS_COLLECTION. Both backends decide every cron route by the caller’s grant on it, the two history routes included. A grant on daas_cron_history opens nothing.

• The gates come from usePermissions().canPerform(collection, action). Administrators pass every gate.
• Until the permissions are known, no write control is drawn and the editor takes no edit. The controls appear when the answer is in, so a user without a right does not see its button first. Reading does not wait: the list and the job load at once. A later refresh of the permissions (a renewed token, another scope) keeps the controls as they were until its answer is in.
• A row menu with no allowed action is not drawn.
• The gates only hide controls. The API enforces the same collection, so a hidden button is not the protection.
• Gate your navigation link too, so a user without read access to daas_cron_jobs does not see Cron Jobs in the sidebar.
• A session that must pass a second factor first gets the access-denied state with the server’s own sentence.

Pass collection only when your backend decides the cron routes by another name. Gate on a name the API does not use and the buttons no longer match what the API allows.

Both backends

The module works against the Next.js DaaS (Supabase) and the Go engine. The hooks read both pagination vocabularies (count / totalPages, and meta.filter_count / meta.total_pages; meta.total / limit / offset for runs), accept data: null as an empty page, and always send the paging parameters.

The routes it calls:

• GET, POST /api/cron; GET, PATCH, DELETE /api/cron/[id]
• POST /api/cron/[id]/run and /api/cron/[id]/clone
• GET /api/cron/history and /api/cron/[id]/history
• GET /api/permissions/me and, for a user who is not an administrator, /api/permissions/daas_cron_jobs (the gates)

What a job’s code can call through services differs per backend. The code a new job starts with runs unchanged on both.

Prerequisites

• DaaSProvider above the pages. The module installs under the authenticated layout, where DaaSProviderWrapper supplies the DaaS URL, the session token and the tenant scope header.
• <Notifications /> from @mantine/notifications mounted once. Saves, row actions, deletes and failed loads report through it. The generated root layout mounts it.
• An i18n provider for a language other than English. The strings are the cron namespace, shipped in English and Indonesian. The generated I18nProvider selects the catalog for the active locale. To change a string, set it under buildpad.cron in your dictionary, or pass translations to one component. Without a provider the components render the English defaults. Dates follow the locale and the time zone of the provider.
• No extra npm package, and no extra styling. The components use the design tokens through the Mantine theme and follow the color scheme. The console of the run log is dark in both color schemes. See the Styleguide.

See the components live

Every surface is in the Cron Storybook. Run it locally with pnpm storybook:cron (port 6014). The fixture stories run on mock data; the CronJobDetail → CustomCodeEditor story shows the renderCodeEditor slot. The Live DaaS stories of CronJobsManager and CronJobDetail connect to a real DaaS instance through the storybook-host proxy (pnpm dev:host).