Lectionary Calculator & Calendar

TypeScript tools for calculating the Western Christian liturgical calendar and rendering Lutheran lectionary data.

This repository contains:

• an ES module library consumable directly from GitHub
• a React web app built with Vite
• bundled lectionary data files used by the app

The codebase currently supports both major lectionary modes:

• 1-year lectionary — the historic 57-week cycle with Gesima Sundays and Trinity numbering
• 3-year lectionary — Series A/B/C with Epiphany 6-8 support and Proper Sundays in Ordinary Time

Source: https://github.com/stanlemon/lectionary-js

Features

• Calculate anchor dates such as Advent, Epiphany, Easter, Pentecost, and Transfiguration
• Determine one-year liturgical week numbers with Week
• Determine three-year series and week/proper assignments with Series and ThreeYearWeek
• Build month grids for calendar UIs with CalendarBuilder
• Load and merge lectionary, festival, daily, and commemoration propers in the bundled app

Install

This package is not currently published to the npm registry. Install it directly from GitHub:

pnpm add github:stanlemon/lectionary-js

The package name remains @stanlemon/lectionary, so imports still look like:

import { Week } from "@stanlemon/lectionary";

Node 24.15.0+ is the current supported runtime for this repository.

Usage

The public library contract is Date-only at the boundary:

• exported APIs accept JavaScript Date values where they take dates
• exported date-returning APIs return fresh JavaScript Date instances
• all returned dates represent local calendar dates at local midnight

Day.js remains an internal implementation detail and is not part of the public contract.

One-Year Calendar

import { Week, Year } from "@stanlemon/lectionary";

const date = new Date(2026, 5, 14); // June 14, 2026
const toDateKey = (value) =>
  [
    value.getFullYear(),
    String(value.getMonth() + 1).padStart(2, "0"),
    String(value.getDate()).padStart(2, "0"),
  ].join("-");

const week = new Week(date).getWeek();
const easter = toDateKey(new Year(2026).getEaster());

console.log({ week, easter });

Three-Year Calendar

import { Series, Sundays, ThreeYearWeek } from "@stanlemon/lectionary";

const date = new Date(2026, 5, 7); // June 7, 2026

const series = new Series(date).getSeries();
const week = new ThreeYearWeek(date).getWeek();

console.log(series); // "A"
console.log(week === Sundays.PROPER_5); // true

Repository Development

This repository includes the calculator library and a React app for browsing the lectionary.

Install dependencies:

pnpm install

Start the Vite dev server:

pnpm start

Build the production app:

pnpm build

Run tests:

pnpm test

Check formatting and linting:

pnpm lint
pnpm lint:format

Run the TypeScript type checker:

pnpm typecheck

Repository Layout

• lib/ — TypeScript core calendar logic and public library exports
• lib/3year/ — three-year series, week, year, and loader logic
• app/ — React app, routing, and presentation
• data/ — bundled lectionary, festival, daily, and commemoration JSON files used by the app

Contributing

The propers data in this repository has largely been entered and maintained by hand. If you spot an error, open an issue or submit a pull request.

This repository is not intended to be an exhaustive catalog of Christian lectionaries. If you want to adapt the code for another tradition, the library is reusable, but that does not imply those lectionaries will be added here.

Functional changes should include a clear description and pass:

• pnpm lint:format
• pnpm typecheck
• pnpm test

License

Code in this repository is available under the MIT license. Lectionary data belongs to the church at large throughout time.