calendaryjs

A tiny, composable calendar & recurrence engine. Model any calendar system — lunar, liturgical, hijri — or event rule as a plugin.

Get started View on npm

Install once, compose anything

import { calendary } from "calendaryjs";
import { every, date } from "calendaryjs/builder";
import { lunar } from "calendaryjs-plugin-lunar";

const cal = calendary().use(lunar());

cal.addGroup({
  id: "holidays",
  events: [
    every("year").on(date(1, 1)).title("New Year"),
    every("year").on(lunar.date(1, 1)).title("Lunar New Year"),
  ],
});

// resolves lunar → solar automatically
cal.getEventsInRange("2025-01-01", "2025-12-31");

Why calendaryjs

Calendar-agnostic core

The engine computes days, recurrence and events. Calendar systems are plugins — install only what you need.

Dates other libs can't

Lunar New Year, Easter +49, Eid — recurrences that RRULE can’t express. calendaryjs computes them and exports plain dates.

Tiny & tree-shakeable

~5KB core, zero runtime dependencies, dual ESM/CJS, source-direct TypeScript.

npm-native plugins

No custom CLI, no parallel registry. npm i, import, cal.use(). Build and publish your own.

TypeScript-first

Strict types throughout; plugins extend CalendarDay via module augmentation.

Pure & stateless

Runs in the browser, Node, edge, and React Native. No side effects.

Calendar systems, as plugins

Plugin	Install	Scope
`calendaryjs-plugin-lunar`	`npm i calendaryjs-plugin-lunar`	Lunisolar conversion + lunar events
`calendaryjs-plugin-liturgical`	`npm i calendaryjs-plugin-liturgical`	Roman Catholic calendar (Easter, seasons)
`calendaryjs-plugin-hijri`	`npm i calendaryjs-plugin-hijri`	Islamic (Hijri, tabular) conversion + events

…or author your own — discovered on npm via the calendaryjs-plugin keyword.

Get started How plugins work