Islamic Utils

A comprehensive, zero-dependency JavaScript library for Islamic calculations: prayer times, Hijri calendar conversions, Qibla direction, moon phases, sighting predictions, and events. Supports multiple madhabs, regions (e.g., Saudi Arabia, Pakistan), and bilingual output (English/Arabic).

• Lightweight & Pure JS: No external dependencies.
• Accurate & Customizable: Regional adjustments, madhab support, high-latitude modes.
• Bilingual: English and Arabic for month names and events.
• Production-Ready: Used in prayer apps, calendars, and more.

Installation

npm install islamic-utils

Features

Prayer Times Calculation: Fajr, Dhuhr, Asr, Maghrib, Isha, plus Imsak, Midnight, First/Third of Night. Supports madhabs (Shafi/Hanafi), methods (MWL, ISNA, Makkah, etc.), tuning, high latitudes. Hijri ↔ Gregorian Calendar: Conversions, full monthly calendars, regional moon-sighting adjustments. Qibla Direction: Bearing and cardinal direction from any lat/long. Moon Phase & Sighting: Phase info, illumination, and sighting prediction (age, altitude, regional rules). Islamic Events: New Year, Ashura, Eid, etc., with dates in both calendars (EN/AR). Region Registry: Pre-configured for Global, Saudi Arabia, Pakistan, India, etc.; extensible. Utilities: Astronomy math, Islamic date utils.

Quick Start

import { PrayerTimesCalculator, IslamicCalendar, getQiblaDirection, isMoonSighted, getIslamicEventsForYear, methods } from 'islamic-utils';

// Prayer Times (Makkah method)
const pt = new PrayerTimesCalculator();
const times = pt.getTimes({
  date: '2025-10-30',
  latitude: 21.4225,
  longitude: 39.8262,
  method: methods.Makkah,
  timezone: 'Asia/Riyadh'
});
console.log(times.data.timings); // { Fajr: '04:23', Dhuhr: '11:42', ... }

// Hijri Calendar (October 2025, Arabic)
const cal = new IslamicCalendar({ region: 'Pakistan' });
const oct2025 = cal.getHijriCalendar(2025, 10, 'ar');
console.log(oct2025[0]); // { gregorian: '2025-10-01', hijri: { year: 1447, month: 3, day: 8, monthName: 'ربيع الأول' } }

// Qibla from New York
const qibla = getQiblaDirection(40.7128, -74.0060);
console.log(qibla); // { bearing: 58.123, direction: 'NE' }

// Moon Sighting Prediction (Ramadan start?)
const sighting = isMoonSighted(new Date('2025-03-29'), 24.7136, 46.6753, { minAgeHours: 16 });
console.log(sighting.sighted ? 'Moon sighted!' : 'Not yet');

// Islamic Events (1447 AH, Arabic)
const events = getIslamicEventsForYear(1447, { lang: 'ar', region: 'Saudi Arabia' });
console.log(events.find(e => e.key === 'ramadan_start')); // { name: 'بداية رمضان', ... }

API Reference

PrayerTimesCalculator

const pt = new PrayerTimesCalculator({ defaultMethodKey: 'MWL' });
pt.getTimes({ date, latitude, longitude, method, madhab, timezone, tune, midnightMode, higherLatitude });

IslamicCalendar

const cal = new IslamicCalendar({ region: 'Saudi Arabia' }); cal.toHijri(date, lang); // Gregorian → Hijri cal.toGregorian(hijriYear, hijriMonth, hijriDay); // Hijri → Gregorian cal.getHijriCalendar(gregorianYear, gregorianMonth, lang); // Full Gregorian month → Hijri dates cal.getGregorianCalendar(hijriYear, hijriMonth, lang); // Full Hijri month → Gregorian dates

Qibla

getQiblaDirection(latitude, longitude); // { bearing, direction }

MoonPhase

getMoonPhaseInfo(date); // { age, illumination, phase }
isMoonSighted(date, latitude, longitude, { minAgeHours, minAltitudeDeg, minIllumination, regionAdjustment });

Events

getIslamicEventsForYear(hijriYear, { lang, region });

RegionRegistry

registerRegion('MyRegion', { adjustment: -1, timezone: 'Asia/MyTZ' });
getRegion('MyRegion');

Localization

Pass lang: 'ar' for Arabic output in calendars and events.

Customization

Methods: Use methods.MWL, etc.

Tuning: tune: [0,2,0,3,0,0,0,0,0] (minutes offsets for each prayer).

High Latitudes: higherLatitude: 'ANGLE_BASED'.

Contributing

Fork, PR, or open issues on GitHub. Tests: npm test.

License

MIT