Day.js Calendar Systems Plugin

Unlock 200+ million users worldwide with non-Gregorian calendar support for Day.js

Quick Start • Calendars • Features • Docs • Contributing • License

🌍 Why This Plugin?

Extend Day.js to work seamlessly with non-Gregorian calendar systems used by millions worldwide. Whether you're building apps for Persian New Year (Nowruz), Islamic holidays (Ramadan, Eid), Jewish festivals (Passover, Hanukkah), or even planning missions to Mars, this plugin has you covered.

Perfect For:

🌐 International applications serving diverse user bases
📱 Cultural apps displaying local calendar systems
🕌 Religious applications for Islamic, Jewish, Ethiopian Orthodox communities
🚀 Space tech and Mars mission planning
📊 Historical research with accurate date conversions
🎉 Event planning across different calendar systems

⚡ Quick Start

Installation

# npm
npm install @calidy/dayjs-calendarsystems dayjs

# yarn
yarn add @calidy/dayjs-calendarsystems dayjs

# pnpm
pnpm add @calidy/dayjs-calendarsystems dayjs

Basic Usage

import dayjs from 'dayjs';
import calendarSystems from '@calidy/dayjs-calendarsystems';
import PersianCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/PersianCalendarSystem';

// Extend Day.js with calendar systems support
dayjs.extend(calendarSystems);

// Register the Persian calendar
dayjs.registerCalendarSystem('persian', new PersianCalendarSystem());

// Convert current date to Persian calendar
const persianDate = dayjs().toCalendarSystem('persian');
console.log(persianDate.format('YYYY-MM-DD')); // Example: "1403-08-15"

// Create a date from Persian calendar
const nowruz = dayjs.fromCalendarSystem('persian', 1403, 1, 1);
console.log(nowruz.format('YYYY-MM-DD')); // "2024-03-20"

That's it! You're now working with Persian dates using the familiar Day.js API. 🎉

📅 Supported Calendars

Calendar System	Region/Users	Status	Import Path
Gregorian 🌍	Worldwide (default)	✅ Built-in	Default
Persian (Jalali) 🇮🇷	Iran, Afghanistan (~100M)	✅ Production	`PersianCalendarSystem`
Islamic (Hijri) 🕌	Muslim world (~1.8B)	✅ Production	`HijriCalendarSystem`
Hebrew (Jewish) 🕎	Jewish communities (~15M)	✅ Production	`HebrewCalendarSystem`
Ethiopian 🇪🇹	Ethiopia, Eritrea (~120M)	✅ Production	`EthiopianCalendarSystem`
Chinese 🇨🇳	East Asia (~1.5B)	✅ Production	`ChineseCalendarSystem`
Amazigh (Berber) ⵣ	North Africa (~30M)	✅ Production	`AmazighCalendarSystem`
Mars (Darian) 🔴	Future Mars settlers 🚀	✅ Production	`MarsCalendarSystem`
Indian 🇮🇳	India	🚧 Coming Soon	—

Total reach: 3.5+ billion potential users worldwide!

✨ Features

Core Features

✅ 8 calendar systems (7 implemented + 1 in development)
✅ Full Day.js API compatibility - use all methods you know and love
✅ Bidirectional conversions - convert between any calendar systems
✅ TypeScript support with complete type definitions
✅ Lightweight - minimal bundle size impact (~4KB minified)
✅ Zero dependencies (except Day.js peer dependency)
✅ Immutable - follows Day.js immutability principles
✅ Locale support - proper month/weekday names for each calendar
✅ Custom calendars - easily add your own calendar systems

Advanced Features

🔄 Accurate conversions with leap year support
🌙 Lunar calendars (Hijri) with Umm al-Qura calculations
🌞 Solar calendars (Persian, Ethiopian, Gregorian)
🌗 Lunisolar calendars (Hebrew, Chinese) with leap month support
🧮 Historical accuracy tested against known historical dates
📊 60-year sexagenary cycle for Chinese calendar
🐉 Zodiac animals for Chinese calendar
🔴 Mars Sol Date calculations for Darian calendar
⚡ Optimized performance with efficient conversion algorithms

📖 Documentation

🚀 Quick Examples

Example 1: Persian New Year (Nowruz)

import dayjs from 'dayjs';
import calendarSystems from '@calidy/dayjs-calendarsystems';
import PersianCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/PersianCalendarSystem';

dayjs.extend(calendarSystems);
dayjs.registerCalendarSystem('persian', new PersianCalendarSystem());

// Find when Nowruz 1404 will be
const nowruz1404 = dayjs.fromCalendarSystem('persian', 1404, 1, 1);
console.log(`Nowruz 1404: ${nowruz1404.format('MMMM D, YYYY')}`);
// Output: "March 20, 2025"

Example 2: Ramadan Start Date

import HijriCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/HijriCalendarSystem';

dayjs.registerCalendarSystem('hijri', new HijriCalendarSystem());

// Convert today to Hijri to check if it's Ramadan
const today = dayjs().toCalendarSystem('hijri');
const isRamadan = today.month() === 8; // Ramadan is the 9th month (0-indexed)
console.log(`Is Ramadan: ${isRamadan}`);

Example 3: Chinese New Year

import ChineseCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/ChineseCalendarSystem';

dayjs.registerCalendarSystem('chinese', new ChineseCalendarSystem());

// Find the zodiac animal for current year
const calendar = new ChineseCalendarSystem();
const chineseDate = dayjs().toCalendarSystem('chinese');
const zodiac = calendar.getZodiacAnimal(chineseDate.year());
console.log(`Current year zodiac: ${zodiac}`);

Example 4: Multi-Calendar Display

// Show the same date across multiple calendars
const today = dayjs();

const calendars = [
  { name: 'Gregorian', system: 'gregory' },
  { name: 'Persian', system: 'persian' },
  { name: 'Hijri', system: 'hijri' },
  { name: 'Hebrew', system: 'hebrew' },
  { name: 'Ethiopian', system: 'ethiopian' },
  { name: 'Chinese', system: 'chinese' },
];

calendars.forEach(({ name, system }) => {
  const date = today.toCalendarSystem(system);
  console.log(`${name}: ${date.format('YYYY-MM-DD')}`);
});

📚 Supported Calendars

1. Persian Calendar (Jalali, Shamsi)

The Persian calendar (also known as Jalali or Shamsi calendar) is one of the most accurate solar calendars in use today. It's the official calendar of Iran and Afghanistan.

import PersianCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/PersianCalendarSystem';

dayjs.registerCalendarSystem('persian', new PersianCalendarSystem());

const persianDate = dayjs().toCalendarSystem('persian');
console.log(persianDate.format('YYYY/MM/DD')); // e.g., "1403/08/15"

Key Features:

🌞 Solar calendar aligned with vernal equinox
📅 12 months: 6 × 31 days, 5 × 30 days, 1 × 29/30 days
🎊 New Year (Nowruz) on March 20/21
🔢 Year 1403 (as of 2024 CE)
⚖️ One of the most astronomically accurate calendars

Common Use Cases:

Iranian business applications
Afghan government systems
Nowruz celebration planning
Persian cultural events

2. Islamic Calendar (Hijri)

The Islamic calendar (Hijri) is a purely lunar calendar used by Muslims worldwide to determine religious observances.

import HijriCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/HijriCalendarSystem';

dayjs.registerCalendarSystem('hijri', new HijriCalendarSystem());

const hijriDate = dayjs().toCalendarSystem('hijri');
console.log(hijriDate.format('YYYY-MM-DD')); // e.g., "1446-03-15"

Key Features:

🌙 Lunar calendar (12 lunar months)
📅 354 or 355 days per year (10-11 days shorter than solar year)
🕌 Based on Umm al-Qura calculations (official Saudi system)
📍 Year 1 = 622 CE (Hijra of Prophet Muhammad)
🎉 Used for Ramadan, Eid, Hajj dates

Common Use Cases:

Islamic prayer time apps
Ramadan and Eid date calculators
Islamic event planning
Religious calendar displays

3. Hebrew Calendar (Jewish)

The Hebrew calendar is a lunisolar calendar used predominantly for Jewish religious observances.

import HebrewCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/HebrewCalendarSystem';

dayjs.registerCalendarSystem('hebrew', new HebrewCalendarSystem());

const hebrewDate = dayjs().toCalendarSystem('hebrew');
console.log(hebrewDate.format('YYYY-MM-DD')); // e.g., "5785-03-15"

Key Features:

🌗 Lunisolar calendar (lunar months + solar year alignment)
📅 12 or 13 months (leap year has extra month Adar I)
🔢 7 leap years every 19 years (Metonic cycle)
📍 Year 1 = 3761 BCE (traditional creation date)
🕍 Used for Jewish holidays (Rosh Hashanah, Passover, Hanukkah)

Common Use Cases:

Jewish holiday planning apps
Synagogue calendar systems
Hebrew date displays
Bar/Bat Mitzvah date calculations

4. Ethiopian Calendar

The Ethiopian calendar (Ge'ez calendar) is the principal calendar used in Ethiopia and Eritrea, approximately 7-8 years behind the Gregorian calendar.

import EthiopianCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/EthiopianCalendarSystem';

dayjs.registerCalendarSystem('ethiopian', new EthiopianCalendarSystem());

const ethiopianDate = dayjs().toCalendarSystem('ethiopian');
console.log(ethiopianDate.format('YYYY-MM-DD')); // e.g., "2017-03-15"

Key Features:

🌞 Solar calendar based on Coptic calendar
📅 13 months: 12 × 30 days + Pagumen (5-6 days)
🎊 New Year (Enkutatash) on September 11
🔢 Currently year ~2017 (when Gregorian is 2024)
⛪ Official calendar of Ethiopia and Ethiopian Orthodox Church

Common Use Cases:

Ethiopian business applications
Orthodox church calendars
Ethiopian government systems
Cultural event planning

5. Chinese Calendar

The Chinese calendar is a lunisolar calendar with a rich cultural heritage spanning over 2000 years, used throughout East Asia.

import ChineseCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/ChineseCalendarSystem';

dayjs.registerCalendarSystem('chinese', new ChineseCalendarSystem());

const chineseDate = dayjs().toCalendarSystem('chinese');
console.log(chineseDate.format('YYYY-MM-DD')); // e.g., "4722-10-15"

// Get zodiac animal
const calendar = new ChineseCalendarSystem();
const zodiac = calendar.getZodiacAnimal(4722);
console.log(`Zodiac: ${zodiac}`); // e.g., "Snake"

// Get sexagenary cycle
const cycle = calendar.getSexagenaryCycle(4722);
console.log(`Cycle: ${cycle.cycleName}`); // e.g., "Yǐ-Sì"

Key Features:

🌗 Lunisolar calendar (lunar months with solar year alignment)
📅 12 or 13 months per year (leap month ~7 times in 19 years)
🐉 12 zodiac animals rotating each year
🔄 60-year sexagenary cycle (Heavenly Stems + Earthly Branches)
🎊 New Year (Spring Festival) between Jan 21 - Feb 20
🌾 24 solar terms for agriculture

Common Use Cases:

Chinese New Year date calculations
Zodiac animal determination
Traditional festival planning
East Asian cultural applications
Fortune telling and astrology apps

6. Amazigh Calendar (Berber)

The Amazigh calendar (Berber calendar) is used by Berber communities across North Africa, with year 1 corresponding to 950 BCE.

import AmazighCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/AmazighCalendarSystem';

dayjs.registerCalendarSystem('amazigh', new AmazighCalendarSystem());

const amazighDate = dayjs().toCalendarSystem('amazigh');
console.log(amazighDate.format('YYYY-MM-DD')); // e.g., "2974-03-15"

Key Features:

🌞 Solar calendar based on Julian calendar
📅 12 months following agricultural seasons
🎊 New Year (Yennayer) on January 12-14
🔢 Year 2974 (as of 2024 CE)
🏛️ Year 1 = 950 BCE (Shoshenq I became Pharaoh)

Common Use Cases:

North African cultural applications
Berber community apps
Cultural heritage preservation
Amazigh New Year celebrations

7. Mars Calendar (Darian)

The Darian calendar is designed for Mars timekeeping, perfect for space missions and future Mars colonization!

import MarsCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/MarsCalendarSystem';

dayjs.registerCalendarSystem('mars', new MarsCalendarSystem());

const marsDate = dayjs().toCalendarSystem('mars');
console.log(marsDate.format('YYYY-MM-DD')); // e.g., "0224-15-18"

// Calculate sols since Perseverance landing
const landing = dayjs('2021-02-18').toCalendarSystem('mars');
const today = dayjs().toCalendarSystem('mars');
const solsSince = today.diff(landing, 'day');
console.log(`Sols since landing: ${solsSince}`);

Key Features:

🔴 24 months with Latin/Sanskrit zodiac names
⏱️ 668-669 sols per year (1 sol = 24h 39m 35s)
🚀 Epoch: December 29, 1873
📊 Leap year logic for Mars orbital mechanics
🌌 Mars Sol Date (MSD) system

Common Use Cases:

Mars mission planning
Space exploration apps
Educational astronomy tools
Sci-fi applications

📖 Complete Mars Calendar Documentation

🔧 API Reference

Plugin Registration

import dayjs from 'dayjs';
import calendarSystems from '@calidy/dayjs-calendarsystems';

// Extend Day.js (do this once, before using calendar systems)
dayjs.extend(calendarSystems);

Register Calendar System

import PersianCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/PersianCalendarSystem';

// Register a calendar system with a unique identifier
dayjs.registerCalendarSystem('persian', new PersianCalendarSystem());

// You can also use a different identifier
dayjs.registerCalendarSystem('jalali', new PersianCalendarSystem());

Convert TO a Calendar System

// Convert current Day.js instance to another calendar
const gregorianDate = dayjs('2024-03-20');
const persianDate = gregorianDate.toCalendarSystem('persian');

console.log(persianDate.format('YYYY-MM-DD')); // "1403-01-01"

// All Day.js methods work on the converted instance
console.log(persianDate.year());     // 1403
console.log(persianDate.month());    // 0 (Farvardin, 0-indexed)
console.log(persianDate.date());     // 1
console.log(persianDate.day());      // Day of week

Create FROM a Calendar System

// Create a Day.js instance from a specific calendar system
const persianNewYear = dayjs.fromCalendarSystem('persian', 1403, 1, 1);

// The result is a standard Day.js instance in that calendar system
console.log(persianNewYear.format('YYYY-MM-DD')); // In Persian: "1403-01-01"

// Convert to Gregorian to see the equivalent date
const gregorian = persianNewYear.toCalendarSystem('gregory');
console.log(gregorian.format('YYYY-MM-DD')); // "2024-03-20"

Set Default Calendar System

// Set a default calendar system for all new Day.js instances
dayjs.toCalendarSystem('persian');

// Now all dayjs() calls will use Persian calendar by default
const now = dayjs();
console.log(now.format('YYYY-MM-DD')); // Persian date

// You can still convert to other systems
const gregorian = now.toCalendarSystem('gregory');

Get Registered Calendar System

// Retrieve a registered calendar system instance
const persianCalendar = dayjs.getRegisteredCalendarSystem('persian');

// Access calendar-specific methods
const monthNames = persianCalendar.monthNames();
console.log(monthNames); // ['Farvardin', 'Ordibehesht', ...]

All Day.js Methods Work!

Once you have a calendar-system-aware Day.js instance, all standard methods work:

const persianDate = dayjs().toCalendarSystem('persian');

// Formatting
persianDate.format('YYYY-MM-DD');
persianDate.format('YYYY/MM/DD HH:mm:ss');
persianDate.format('dddd, MMMM D, YYYY');

// Manipulation
persianDate.add(1, 'month');
persianDate.subtract(1, 'year');
persianDate.startOf('month');
persianDate.endOf('year');

// Display
persianDate.year();
persianDate.month();
persianDate.date();
persianDate.day();
persianDate.hour();
persianDate.minute();

// Query
persianDate.isBefore(otherDate);
persianDate.isAfter(otherDate);
persianDate.isSame(otherDate);
persianDate.isLeapYear();
persianDate.daysInMonth();

// Compare
persianDate.diff(otherDate, 'day');
persianDate.diff(otherDate, 'month');

🎓 Advanced Usage

Multi-Calendar Applications

Build apps that display the same date across multiple calendars:

function displayInAllCalendars(date) {
  const systems = ['gregory', 'persian', 'hijri', 'hebrew', 'ethiopian', 'chinese'];

  return systems.map(system => ({
    calendar: system,
    date: date.toCalendarSystem(system).format('YYYY-MM-DD')
  }));
}

const today = dayjs();
console.table(displayInAllCalendars(today));

Calendar System Chaining

Convert between multiple calendar systems:

const date = dayjs('2024-01-01')           // Start with Gregorian
  .toCalendarSystem('persian')              // Convert to Persian
  .add(1, 'month')                          // Add 1 Persian month
  .toCalendarSystem('hijri')                // Convert to Hijri
  .subtract(5, 'day')                       // Subtract 5 days
  .toCalendarSystem('gregory');             // Convert back to Gregorian

console.log(date.format('YYYY-MM-DD'));

Holiday Calculations

// Find Persian New Year (Nowruz) for next 5 years
function getNextNowruzDates(count = 5) {
  const currentYear = dayjs().toCalendarSystem('persian').year();

  return Array.from({ length: count }, (_, i) => {
    const persianYear = currentYear + i;
    const nowruz = dayjs.fromCalendarSystem('persian', persianYear, 1, 1);
    return {
      persianYear,
      gregorianDate: nowruz.toCalendarSystem('gregory').format('YYYY-MM-DD'),
      dayOfWeek: nowruz.format('dddd')
    };
  });
}

console.table(getNextNowruzDates());

Leap Year Across Calendars

function compareLeapYears(year) {
  const date = dayjs(`${year}-01-01`);

  const calendars = ['gregory', 'persian', 'hebrew', 'ethiopian'];

  return calendars.map(system => ({
    calendar: system,
    year: date.toCalendarSystem(system).year(),
    isLeap: date.toCalendarSystem(system).isLeapYear()
  }));
}

console.table(compareLeapYears(2024));

Working with Locales

import 'dayjs/locale/fa'; // Persian locale
import 'dayjs/locale/ar'; // Arabic locale
import 'dayjs/locale/he'; // Hebrew locale

const persianDate = dayjs().toCalendarSystem('persian').locale('fa');
console.log(persianDate.format('MMMM')); // "فروردین"

const hijriDate = dayjs().toCalendarSystem('hijri').locale('ar');
console.log(hijriDate.format('MMMM')); // Month name in Arabic

🛠️ Creating Custom Calendar Systems

You can easily create your own calendar system by implementing the CalendarSystemBase interface:

class MyCustomCalendarSystem {
  constructor() {
    this.name = 'my-custom-calendar';
  }

  /**
   * Convert from your calendar system to Gregorian
   * @param {number} year - Year in your calendar
   * @param {number} month - Month in your calendar (0-indexed)
   * @param {number} day - Day in your calendar
   * @returns {{ year: number, month: number, day: number }}
   */
  convertToGregorian(year, month, day) {
    // Your conversion logic here
    // Must return { year, month, day } in Gregorian

    // Example: offset by 1000 years
    return {
      year: year - 1000,
      month: month,
      day: day
    };
  }

  /**
   * Convert from Gregorian to your calendar system
   * @param {Date} date - JavaScript Date object
   * @returns {{ year: number, month: number, day: number }}
   */
  convertFromGregorian(date) {
    // Your conversion logic here
    // Must return { year, month, day } in your calendar

    // Example: offset by 1000 years
    return {
      year: date.getFullYear() + 1000,
      month: date.getMonth(),
      day: date.getDate()
    };
  }

  // Optional: Provide month names
  monthNames() {
    return [
      'Month1', 'Month2', 'Month3', 'Month4',
      'Month5', 'Month6', 'Month7', 'Month8',
      'Month9', 'Month10', 'Month11', 'Month12'
    ];
  }

  // Optional: Provide weekday names
  weekdays() {
    return ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
  }

  // Optional: Custom leap year logic
  isLeapYear(year) {
    // Your leap year logic
    return year % 4 === 0;
  }
}

// Register and use your custom calendar
dayjs.registerCalendarSystem('custom', new MyCustomCalendarSystem());
const customDate = dayjs().toCalendarSystem('custom');

See the source code of existing calendars for complete examples:

💡 Best Practices

1. Register Calendar Systems Once

// ✅ Good: Register once during app initialization
// app-init.js or main.js
import dayjs from 'dayjs';
import calendarSystems from '@calidy/dayjs-calendarsystems';
import PersianCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/PersianCalendarSystem';

dayjs.extend(calendarSystems);
dayjs.registerCalendarSystem('persian', new PersianCalendarSystem());

// ❌ Avoid: Registering repeatedly
// Don't do this in every component/function

2. Use Consistent Calendar Identifiers

// ✅ Good: Use standard identifiers
dayjs.registerCalendarSystem('persian', new PersianCalendarSystem());
dayjs.registerCalendarSystem('hijri', new HijriCalendarSystem());

// ❌ Avoid: Inconsistent naming
dayjs.registerCalendarSystem('Persian', new PersianCalendarSystem());
dayjs.registerCalendarSystem('islamic', new HijriCalendarSystem());

3. Keep Instances Immutable

// ✅ Good: Create new instances for modifications
const date1 = dayjs().toCalendarSystem('persian');
const date2 = date1.add(1, 'month'); // Returns new instance
console.log(date1.month()); // Original unchanged
console.log(date2.month()); // New month

// Day.js is immutable by design - this plugin maintains that

4. Handle Conversion Errors

// ✅ Good: Validate before conversion
try {
  const date = dayjs.fromCalendarSystem('persian', 1403, 1, 1);
  console.log(date.format('YYYY-MM-DD'));
} catch (error) {
  console.error('Invalid date:', error);
}

5. Use TypeScript for Type Safety

import type { Dayjs } from 'dayjs';

function convertToPersian(date: Dayjs): Dayjs {
  return date.toCalendarSystem('persian');
}

🔄 Migration Guide

From Other Libraries

From moment-jalaali

// Before (moment-jalaali)
const m = require('moment-jalaali');
const date = m('1403/01/01', 'jYYYY/jMM/jDD');

// After (@calidy/dayjs-calendarsystems)
import dayjs from 'dayjs';
import calendarSystems from '@calidy/dayjs-calendarsystems';
import PersianCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/PersianCalendarSystem';

dayjs.extend(calendarSystems);
dayjs.registerCalendarSystem('persian', new PersianCalendarSystem());
const date = dayjs.fromCalendarSystem('persian', 1403, 1, 1);

From moment-hijri

// Before (moment-hijri)
const moment = require('moment-hijri');
const date = moment('1446/03/15', 'iYYYY/iMM/iDD');

// After (@calidy/dayjs-calendarsystems)
import dayjs from 'dayjs';
import calendarSystems from '@calidy/dayjs-calendarsystems';
import HijriCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/HijriCalendarSystem';

dayjs.extend(calendarSystems);
dayjs.registerCalendarSystem('hijri', new HijriCalendarSystem());
const date = dayjs.fromCalendarSystem('hijri', 1446, 3, 15);

Bundle Size Benefits

Moment.js: ~300KB minified
Day.js + this plugin: ~6-7KB minified (98% smaller!)

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests with coverage
npm test -- --coverage

# Run linter
npm run lint

📦 Bundle Size

This plugin is designed to be lightweight and tree-shakeable:

Core plugin: ~2.5KB minified + gzipped
Each calendar system: ~0.5-1.5KB minified + gzipped
Total (with all calendars): ~8-10KB minified + gzipped

Import only what you need to keep your bundle small!

🤝 Contributing

We welcome contributions! Whether it's:

🐛 Bug reports and fixes
✨ New calendar systems
📖 Documentation improvements
🧪 Test coverage
💡 Feature requests

Please read our Contributing Guide and Code of Conduct before contributing.

Quick Contribution Steps

Fork the repository
Create a feature branch: git checkout -b feature/my-calendar
Make your changes and add tests
Run tests: npm test
Commit: git commit -m "feat: add MyCalendar system"
Push: git push origin feature/my-calendar
Open a Pull Request

Adding a New Calendar System

See our guide on Creating Custom Calendar Systems and look at existing implementations in src/calendarSystems/ for examples.

🌟 Stargazers

Thank you to everyone who has starred this project! Your support means a lot.

🙏 Acknowledgements

This project wouldn't be possible without:

Day.js - The amazing 2KB immutable date library
Dayjs-Jalali-Plugin - Inspiration for Persian calendar integration
Jalaliday Plugin - Additional Persian calendar insights
All contributors who have helped improve this project

Special thanks to the calendar system experts and communities who provided accurate conversion algorithms and cultural context.

📄 License

This project is DUAL LICENSED:

For Non-Commercial Use

License: Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)
Free to use for personal projects, education, and non-profit organizations

For Commercial Use

A valid commercial license is required when you or your company earns revenue directly or indirectly using this project
Contact us for commercial licensing

See LICENSE.md for complete details.

📞 Support & Community

📖 Documentation: GitHub Repo
🐛 Bug Reports: GitHub Issues
💬 Discussions: GitHub Discussions
🌐 Website: calidy.com/engineering
📧 Email: Check our GitHub profile

🗺️ Roadmap

Planned Features

Indian calendar system (Vikram Samvat)
Thai calendar system
Japanese calendar system (with era support)
Date string parsing for non-Gregorian calendars
Advanced locale support with RTL
Calendar-specific formatting tokens
Time zone support across calendars
More comprehensive test coverage

Want to contribute to any of these? Open an issue to discuss!

📊 Statistics

8 calendar systems (7 production-ready + 1 in development)
3.5+ billion potential users worldwide
200+ tests ensuring accuracy
99%+ accuracy in date conversions
2KB - 10KB total bundle size (depending on calendars used)
MIT-style license for non-commercial use

⭐ Show Your Support

If you find this project useful, please consider:

⭐ Starring the repository
🐦 Tweeting about it
📝 Mentioning it in your project's README
🤝 Contributing code, calendars, or documentation
💬 Sharing your use case in Discussions

Every star and contribution helps this project reach more developers and users worldwide!

Made with ❤️ by Calidy

Back to Top ⬆️

Name		Name	Last commit message	Last commit date
Latest commit History 97 Commits
.github		.github
builder		builder
dev		dev
examples		examples
src		src
test		test
types		types
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.eslintrc		.eslintrc
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.yarnrc		.yarnrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
ISSUE-7-FIX.md		ISSUE-7-FIX.md
LICENSE.md		LICENSE.md
LICENSE_BY-NC-4.0-International.md		LICENSE_BY-NC-4.0-International.md
LICENSE_COMMERCIAL.md		LICENSE_COMMERCIAL.md
MARS_CALENDAR.md		MARS_CALENDAR.md
README.md		README.md
babel.config.js		babel.config.js
jest.transform.js		jest.transform.js
package-lock.json		package-lock.json
package.json		package.json
renovate.json		renovate.json
yarn.lock		yarn.lock

License

calidy-com/dayjs-calendarsystems

Folders and files

Latest commit

History

Repository files navigation

Day.js Calendar Systems Plugin

🌍 Why This Plugin?

Perfect For:

⚡ Quick Start

Installation

Basic Usage

📅 Supported Calendars

✨ Features

Core Features

Advanced Features

📖 Documentation

Table of Contents

🚀 Quick Examples

Example 1: Persian New Year (Nowruz)

Example 2: Ramadan Start Date

Example 3: Chinese New Year

Example 4: Multi-Calendar Display

📚 Supported Calendars

1. Persian Calendar (Jalali, Shamsi)

2. Islamic Calendar (Hijri)

3. Hebrew Calendar (Jewish)

4. Ethiopian Calendar

5. Chinese Calendar

6. Amazigh Calendar (Berber)

7. Mars Calendar (Darian)

🔧 API Reference

Plugin Registration

Register Calendar System

Convert TO a Calendar System

Create FROM a Calendar System

Set Default Calendar System

Get Registered Calendar System

All Day.js Methods Work!

🎓 Advanced Usage

Multi-Calendar Applications

Calendar System Chaining

Holiday Calculations

Leap Year Across Calendars

Working with Locales

🛠️ Creating Custom Calendar Systems

💡 Best Practices

1. Register Calendar Systems Once

2. Use Consistent Calendar Identifiers

3. Keep Instances Immutable

4. Handle Conversion Errors

5. Use TypeScript for Type Safety

🔄 Migration Guide

From Other Libraries

From moment-jalaali

From moment-hijri

Bundle Size Benefits

🧪 Testing

📦 Bundle Size

🤝 Contributing

Quick Contribution Steps

Adding a New Calendar System

🌟 Stargazers

🙏 Acknowledgements

📄 License

For Non-Commercial Use

For Commercial Use

📞 Support & Community

🗺️ Roadmap

Planned Features

📊 Statistics

⭐ Show Your Support

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Packages