DEV Community

Cover image for Introducing islamic-date: A Simple Islamic/Hijri Date Converter for JavaScript
Cahyanudien Aziz Saputra
Cahyanudien Aziz Saputra

Posted on

Introducing islamic-date: A Simple Islamic/Hijri Date Converter for JavaScript

#islam #hijridate #mabims #ummalqura

Converting between Gregorian and Hijri (Islamic) dates shouldn't be complicated. That's why I built islamic-date — a lightweight, straightforward npm package for handling Islamic calendar dates in JavaScript.

Why I Built This

I created islamic-date for developers who want to build applications that serve communities using multiple calendar systems. Whether you're building:

  • Islamic event applications — Track Ramadan, Eid, and other Islamic holidays
  • Javanese calendar systems — Integrate with traditional Javanese dates that combine Hijri and Javanese cycles
  • Arabic date displays — Show dates in Arabic calendar format for Middle Eastern and Southeast Asian users
  • Multi-cultural platforms — Serve communities in Indonesia, Malaysia, and other regions where Islamic and local calendars matter

I wanted something simple and flexible that could be the foundation for these kinds of applications, without forcing you into a specific UI or framework

Installation

Getting started is as easy as:

npm install islamic-date
Enter fullscreen mode Exit fullscreen mode

Quick Start

Here's how simple it is to use:

import { toHijri, toGregorian } from 'islamic-date';

// Convert Gregorian to Hijri
const hijriDate = toHijri(new Date());
console.log(hijriDate); 
// { year: 1446, month: 7, day: 15 }

// Convert Hijri to Gregorian
const gregorianDate = toGregorian(1446, 7, 15);
console.log(gregorianDate);
// Date object
Enter fullscreen mode Exit fullscreen mode

Key Features

1. Bidirectional Conversion

Convert seamlessly between Gregorian and Hijri calendars in both directions.

2. Multiple Input Formats

The package accepts various date formats to make your life easier:

  • Date objects
  • ISO strings
  • Array format [year, month, day]

3. Accurate Calculations

The conversion algorithms are based on established astronomical calculations to ensure accuracy.

4. TypeScript Support

Full TypeScript support with type definitions included out of the box.

Use Cases

islamic-date is perfect for:

  • Islamic event apps — Build apps for Ramadan schedules, Eid countdowns, Islamic holidays
  • Javanese calendar integration — Combine with Javanese calendar systems (Saka, Pawukon) for traditional events
  • Prayer time applications — Display dates in Hijri alongside prayer times
  • Arabic localization — Show dates in Arabic calendar format for MENA and Southeast Asian markets
  • Cultural heritage apps — Preserve and teach traditional calendar systems
  • Multi-calendar dashboards — Serve users in Indonesia, Malaysia, and other regions with diverse calendar needs (MABIMS and Umm Al-Qura)
  • Event schedulers — Handle Islamic holidays, Javanese ceremonies, and regional observances

Example: Building an Islamic Event App

Here's a practical example for an Islamic event tracker:

import { toHijri, toGregorian } from 'islamic-date';

// Find when Ramadan starts
const ramadanStart = toGregorian(1446, 9, 1);
console.log(`Ramadan 1446 starts on: ${ramadanStart.toLocaleDateString()}`);

// Convert today's date to show in your app
const today = toHijri(new Date());
console.log(`Today in Hijri: ${today.day}/${today.month}/${today.year}`);

// Perfect for building countdown timers, event calendars, 
// or apps that need to display both calendars side-by-side
Enter fullscreen mode Exit fullscreen mode

What Makes It Different?

Unlike heavier alternatives that come with full calendar UI components or require moment.js, islamic-date focuses on doing one thing well: date conversion. This makes it:

  • Faster to install
  • Easier to integrate
  • Smaller bundle size
  • More maintainable

You can use it as a foundation and build your own UI components on top, or simply use it for backend date calculations.

Roadmap

I'm actively working on improving islamic-date. Here's what's coming:

  • Date formatting utilities
  • Month name localization (Arabic, English, and more)
  • Date arithmetic (add/subtract days, months)
  • Holiday detection helpers
  • Even better TypeScript support

Contributing

This is an open-source project, and contributions are welcome! Whether it's:

  • Reporting bugs
  • Suggesting features
  • Improving documentation
  • Submitting pull requests

Check out the GitHub repository to get involved.

Try It Today

Ready to simplify Islamic date handling in your JavaScript projects?

npm install islamic-date
Enter fullscreen mode Exit fullscreen mode

Visit the npm package page for complete documentation and examples.

Found this helpful? Give the package a star on GitHub and share it with other developers who might benefit!

Top comments (0)