Plugins

calendaryjs is calendar-agnostic. The core knows nothing about lunar months or Easter — those live in plugins.

Two kinds of plugin

• Calendar plugins add a calendar system — new event types you register with cal.use() (and can enrich each day, like a Hijri date): lunar, liturgical, hijri. The rest of this guide covers these.
• Integrations bridge an external standard or service at the edge and are not registered with cal.use(): ics serializes generated events to a standard .ics file. Later: Google/Apple sync, ICS import.

Both publish as calendaryjs-plugin-<name> under the calendaryjs-plugin keyword.

Using a plugin

Install from npm and register it with .use():

import { calendary } from "calendaryjs";
import { hijri } from "calendaryjs-plugin-hijri";

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

.use() is chainable, so you can compose several calendar systems:

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

How distribution works

There is no custom installer and no parallel registry. A calendaryjs plugin is an ordinary npm package:

• Install with your package manager: npm i <plugin>.
• Load by importing it and passing it to cal.use().
• Discover every plugin via the calendaryjs-plugin keyword on npm — official and community plugins both publish as calendaryjs-plugin-<name>.

Authoring a plugin

A plugin is a function returning a CalendaryPlugin:

import type { CalendaryPlugin } from "calendaryjs";

export function myPlugin(): CalendaryPlugin {
  return {
    name: "calendaryjs-my-plugin",
    version: "0.1.0",
    eventTypes: {
      "my-type": {
        validate(event): boolean {
          // return true if `event` is a valid my-type event
          return true;
        },
        generate(event, year): Date[] {
          // return the date(s) this event falls on in `year`
          return [];
        },
      },
    },
  };
}

Publish it as calendaryjs-my-plugin with the keyword calendaryjs-plugin so it appears in plugin discovery.