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.

What it isn’t. calendaryjs is the expansion engine — rules → dated occurrences as plain data. It doesn’t persist your data, render the calendar, or deliver notifications (reminders are pre-computed offsets, not fired); wire those to your own stack.

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.add(
  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). add also accepts those objects directly. To organize events into named groups you can toggle or export separately, use cal.addGroup({ id, events }) — see Collections & groups for the recommended way to compose a calendar from several. Event types covers 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").year(2025).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.