DEV Community

Cover image for I built a free cron expression decoder, here's how it works under the hood
Michael Bello
Michael Bello

Posted on

I built a free cron expression decoder, here's how it works under the hood

#webdev #opensource #javascript #ai

The problem

Every developer has been here: you're staring at 0 */4 * * 1-5 in a config file
and you have no idea what it means without running it mentally or Googling it.

I got tired of that. So I built Cron.Explain, a free tool that decodes any cron expression into plain English instantly.

🔗 https://timely-flan-0ca3c1.netlify.app

What it does

Paste any cron expression and you get three things:

1. Plain English explanation
0 9 * * 1-5 → "At 9:00 AM, on Monday through Friday"

2. Field-by-field breakdown
Each of the 5 fields explained individually — minute, hour, day of month, month, day of week.

3. Next 5 run times
The actual dates and times your job will fire next, calculated in your local timezone.

The API

It also ships a free REST API — no key required:

curl -X POST https://timely-flan-0ca3c1.netlify.app/api/explain \
  -H "Content-Type: application/json" \
  -d '{"cron": "0 9 * * 1-5"}'
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "expression": "0 9 * * 1-5",
  "explanation": "At 9:00 AM, on Monday through Friday",
  "fields": { ... },
  "nextRuns": ["2026-02-23T09:00:00.000Z", ...]
}
Enter fullscreen mode Exit fullscreen mode

How I built it

The interesting part: I didn't use any external cron parsing libraries.
The entire parser is hand-rolled in vanilla JavaScript.

The core is a matchesField(value, n, min) function that handles all the special cron characters: *, */n, n-m, n,m, and n/m.

The next-run calculator works by starting from the current minute and incrementing forward, checking each minute against all 5 fields until it finds 5 matches. It caps at 500,000 iterations to handle edge cases like rare monthly schedules.

Tech stack

  • React + Vite (frontend)
  • Netlify Functions (serverless API)
  • Zero dependencies for the parser
  • IBM Plex Mono font because it felt right for a dev tool

What's next

I'm thinking about adding:

  • Cron job monitoring (ping a URL, alert if it hasn't run)
  • Reverse builder (describe a schedule in English, get the cron)
  • More languages in the API docs

The code is open source on GitHub. Would love feedback, especially on cron expressions that break the parser — there are definitely edge cases I haven't covered.

🔗 Live tool: https://timely-flan-0ca3c1.netlify.app
📖 API docs: https://timely-flan-0ca3c1.netlify.app/docs

Top comments (0)