Introduction

calendaryjs is a composable calendar / recurrence engine. A tiny core computes days, recurrence and events; alternative calendar systems (lunar, liturgical, hijri, …) are added as plugins. The core is calendar-agnostic — it knows nothing about lunar months or Easter until you use() a plugin.

Install

npm i calendaryjs

Your first calendar

The builder reads like a sentence — the recommended way to author events:

import { calendary } from "calendaryjs";
import { every, once, date } from "calendaryjs/builder";

const cal = calendary();

cal.addGroup({
  id: "holidays",
  events: [
    every("year").on(date(1, 1)).title("New Year"),
    every("year").on(date(12, 25)).title("Christmas"),
    once("2025-06-15").title("Launch"),
  ],
});

cal.getEventsInRange("2025-01-01", "2025-12-31");

Each builder compiles to a plain config object — the form calendaryjs stores and exports (JSON, ICS). addGroup also accepts those objects directly. See Event types for the underlying shapes.

Querying

cal.getEvents("2025-12-25"); // events on a day
cal.getEventsInRange("2025-01-01", "2025-12-31"); // events in a range
cal.getDay("2025-12-25"); // a day, events sorted by priority

// Advanced — text / type / status / source / categories / metadata / sorting:
cal.search().text("christmas").range("2025-01-01", "2025-12-31").getEvents();
cal.search().type("weekly").status("confirmed").getEvents();

Add a calendar system

Plugins are ordinary npm packages. Install one and pass it to cal.use():

npm i calendaryjs-plugin-lunar

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

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

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

Each plugin adds a builder selector (lunar.date(…), hijri.date(…)).

Official plugins

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

Continue with Plugins and the API reference.