church-liturgy

The Western church year, computed: the date of Easter, the season any date falls in, and the movable feasts that hang off both.

Zero dependencies. About 2 KB. Pure UTC arithmetic, so it works the same in every timezone. Runs in Node and in the browser with no build step.

npm install church-liturgy

Why

Every parish website answers two questions badly: what season is it and when is the holy day. Both are arithmetic nobody wants to redo each year, so the dates get typed in by hand and the page is wrong by February.

All of it is computable. Easter is the Gregorian computus; Ascension is Easter + 39 days; Advent is anchored to Christmas. This does that arithmetic and nothing else.

Quick start

import { season, easterDate, movable, upcoming } from 'church-liturgy';

season(new Date('2026-04-05'));
// { id: 'easter', name: 'Eastertide', colour: 'gold', week: 1, label: 'Eastertide · Week 1' }

easterDate(2026);          // 2026-04-05
movable(2026).ascension;   // 2026-05-14
movable(2026).pentecost;   // 2026-05-24

Colour the page by season, with no flash of the wrong colour:

<script type="module">
  import { applySeason } from 'church-liturgy';
  applySeason();           // sets <html data-season="lent">
</script>

<style>
  :root[data-season="lent"]    { --accent: #5b4b8a; }
  :root[data-season="easter"]  { --accent: #b8860b; }
</style>

The calendar

easter(2026)      // 1775347200000 — a UTC timestamp
easterDate(2026)  // Date 2026-04-05
advent(2026)      // timestamp for Advent Sunday
adventDate(2026)  // Date 2026-11-29

season(date?) returns the season a date falls in, defaulting to now:

| field | example | meaning | |---|---|---| | id | lent | one of advent christmas epiphany lent holyweek easter pentecost ordinary | | name | Lent | display name | | colour | violet | violet · gold · green · oxblood | | week | 3 | week within the season, 1-based | | label | Lent · Third Sunday | long form |

movable(year) returns the Easter-relative feasts as Dates: ashWednesday, palmSunday, goodFriday, holySaturday, easter, divineMercy, ascension, pentecost, trinity, corpusChristi, sacredHeart, and christTheKing.

Christ the King is not an Easter offset, though easter + 238 looks like one. It is the Sunday before Advent, and Advent is anchored to Christmas — so the gap from Easter varies by a week. In 2026 the naive offset lands on Advent Sunday itself.

Feast days

Which feasts a parish keeps, and whether one moves to the nearest Sunday, is set by its bishops' conference and does change — England and Wales restored Ascension to the Thursday in 2018. Getting that wrong on a parish website is a real error about a real obligation.

So the engine computes dates and your config declares status:

import { feastsIn, upcoming, obligationsIn } from 'church-liturgy';

const config = {
  calendar: {
    feasts: [
      { name: 'The Epiphany', on: '01-06', obligation: true, transferToSunday: true },
      { name: 'The Ascension', on: 'easter+39', obligation: true },
      { name: 'Corpus Christi', on: 'corpusChristi', transferToSunday: true },
      { name: 'Christmas Day', on: '12-25', obligation: true },
    ],
  },
};

upcoming(config, new Date(), 4);   // the next four, rolling into next year
obligationsIn(config, 2026);       // only the days of obligation

on accepts a fixed date ("12-25"), an Easter offset ("easter+39", "easter-46"), or any movable() key ("corpusChristi").

A transferred feast keeps both dates, so you can print "Epiphany (observed)" honestly:

feastsIn(config, 2026).find(f => f.name === 'The Epiphany');
// { proper: 2026-01-06, observed: 2026-01-11, date: 2026-01-11, transferred: true, obligation: true }

upcoming() rolls into the following year rather than going blank — the bug every hand-maintained list has in the last fortnight of December.

API

| function | returns | |---|---| | easter(year) / advent(year) | UTC timestamp | | easterDate(year) / adventDate(year) | Date | | season(date?) | { id, name, colour, week, label } | | applySeason(config?, date?) | the season; also sets data-season on <html> (browser) | | movable(year) | the Easter-relative feasts, as Dates | | resolveOn(on, year) | Date or null | | toSunday(date) | the Sunday on or after date | | feastsIn(config, year) | every declared feast, dated and sorted | | upcoming(config, from?, count?) | the next count feasts | | obligationsIn(config, year) | days of obligation only |

TypeScript definitions are bundled. applySeason is the only export that touches the DOM, and only inside its body — importing the package under Node is safe.

Scope

Western calendar only: Roman Catholic and Anglican use, and the Protestant churches that keep the same seasons. It does not compute the Julian/Orthodox Paschalion, sanctoral cycles, or a lectionary.

Valid 1583–4099, the range over which the Gregorian computus holds.

Tested against the published Easter dates, and against the invariants — Easter is a Sunday for every year 1583–2200, Advent is a Sunday 22–28 days before Christmas, and every day of a decade resolves to a known season.

Licence

MIT. Extracted from the engine behind the free church website templates at ChurchCreation, where it colours ten templates by the season and dates their holy-day pages.