· Updated

Building coptic.io

An open-source API for the Coptic Orthodox calendar: daily readings, the Synaxarium, the Agpeya and fasting seasons, served from Cloudflare Workers.

coptic.io is an open-source API and website for the Coptic Orthodox Church calendar. Give it a date and it tells you the Coptic date, the day’s readings from the Katameros, the saints commemorated in the Synaxarium, whether it’s a fasting day, and which liturgical season it falls in.

Why

The Coptic calendar drives a lot of church life: which readings are read on a given day, when the fasts start, when Easter falls. Apps that need this either hardcode it or reimplement the date math themselves. I wanted one open source for it that anyone can build on.

What it covers

  • Gregorian to Coptic date conversion, month views, and an iCalendar feed you can subscribe to
  • The daily Katameros readings, with the full text on request
  • Saints from the Synaxarium by date, by Coptic date, or by name
  • The Agpeya prayer hours, including which hour it is right now
  • Fasting status for any date, a full-year fasting calendar, and the current liturgical season
  • Feasts on a given date and the ones coming up
  • Search across the Bible, the Synaxarium and the Agpeya

Everything is available over REST and GraphQL at api.coptic.io:

curl https://api.coptic.io/api/calendar
# {"dateString":"Tout 30, 1743","day":30,"month":1,"year":1743,"monthString":"Tout"}

How it’s built

It’s a TypeScript monorepo. The API is Hono on Cloudflare Workers, serving GraphQL through GraphQL Yoga next to REST routes whose OpenAPI docs are generated from Zod schemas. The website is Next.js on Vercel, in English, Arabic and Spanish, and a separate Next.js admin panel manages the content.

Three shared packages sit underneath: @coptic/core handles date conversion, the Easter calculation and liturgical seasons; @coptic/client is a small typed client for the API; and @coptic/data bundles the Bible text, Synaxarium and readings for offline use.

The first version was Express with GraphQL, Swagger docs and PM2 on a server. Moving the API to Hono on Workers removed the server entirely, and requests are now answered from whichever Cloudflare location is closest to the caller.

Pulling the calendar logic into @coptic/core came later. Once the website existed, it needed the same date math as the API, and I didn’t want two copies of it drifting apart. Keeping the package free of dependencies means it runs the same in a Worker, in the browser, or in someone else’s project.

Try it

git clone https://github.com/abanobmikaeel/coptic.io.git
cd coptic.io
pnpm install
pnpm dev

Issues and contributions are welcome on GitHub.

← All writing