islam.js

islam.js is a comprehensive JavaScript/TypeScript library designed for Islamic applications. It provides functionalities related to the Quran, Hadith, Dua & Azkar, Prayer Timings, and Hijri Calendar. This package offers multilingual support, a wide range of Tafseers, Hadith collections, and tools to enhance the development of Islamic software solutions.

Features

Quran:
- Support for Dialects: Hafs and Warsh
- 28 Language Translations
- 28 Tafseers (Commentaries) in different languages
Hadith:
- Collections: Kutub al-Sittah (Six Authentic Books) with 5+ Translations
Dua & Azkar:
- 134 categories with over 360 Azkars (supplications)
Prayer Timings:
- Accurate prayer timings for any location worldwide
Hijri Calendar:
- Hijri date conversion and calendar utilities

Installation

To install islam.js, use npm or yarn:

npm install islam.js
# or
yarn add islam.js

Getting Started

Import the library into your JavaScript or TypeScript project and start using the available features.

import { Quran, Hadith } from 'islam.js';

Usage

1. Quran

Supported Translation Languages

Language	`TranslationEnum` value
Albanian	`TranslationEnum.Albanian`
Bulgarian	`TranslationEnum.Balgarian`
Bengali	`TranslationEnum.Bengali`
Chinese	`TranslationEnum.Chinese`
Dutch	`TranslationEnum.Dutch`
English	`TranslationEnum.English`
French	`TranslationEnum.French`
German	`TranslationEnum.German`
Hindi	`TranslationEnum.Hindi`
Indonesian	`TranslationEnum.Indonesian`
Italian	`TranslationEnum.Italian`
Japanese	`TranslationEnum.Japanese`
Korean	`TranslationEnum.Korean`
Norwegian	`TranslationEnum.Norwegian`
Pashto	`TranslationEnum.Pashto`
Persian	`TranslationEnum.Persian`
Portuguese	`TranslationEnum.Portuguese`
Punjabi	`TranslationEnum.Punjabi`
Romanian	`TranslationEnum.Romanian`
Russian	`TranslationEnum.Russian`
Sindhi	`TranslationEnum.Sindhi`
Somalian	`TranslationEnum.Somalian`
Spanish	`TranslationEnum.Spanish`
Tamil	`TranslationEnum.Tamil`
Thai	`TranslationEnum.Thai`
Turkish	`TranslationEnum.Turkish`
Urdu	`TranslationEnum.Urdu`
Uzbek	`TranslationEnum.Uzbek`

Get a chapter by index

import { Quran } from 'islam.js';
const quran = new Quran();
const chapter = quran.getChapterByIndex(108);
console.log(chapter);

//Output
{
   "name": "الكوثر",
   "type": "مكيّة",
   "englishName": "Al-Kawthar",
   "number": 108,
   "numberOfLetters": 42,
   "numberOfVerses": 3,
   "numberOfWords": 10,
   "verses": [
      "إِنَّا أَعْطَيْنَاكَ الْكَوْثَرَ",
      "فَصَلِّ لِرَبِّكَ وَانْحَرْ",
      "إِنَّ شَانِئَكَ هُوَ الْأَبْتَرُ"
   ]
}

Get a chapter by name

By default the dialect will be Hafs but we can change it to Warsh as well.

import { Quran, DialectEnum } from 'islam.js';
const quran = new Quran(DialectEnum.Warsh);
const chapter = quran.getChapterByName('Al-Ekhlas');
console.log(chapter);

//Output
{
   "name": "الإخلاص",
   "type": "مكيّة",
   "englishName": "Al-Ekhlas",
   "number": 112,
   "numberOfLetters": 47,
   "numberOfVerses": 4,
   "numberOfWords": 15,
    "verses": [
      "قُلْ هُوَ اللَّهُ أَحَدٌ",
      "اللَّهُ الصَّمَدُ",
      "لَمْ يَلِدْ وَلَمْ يُولَدْ",
      "وَلَمْ يَكُن لَّهُ كُفُوًا أَحَدٌ"
   ]
}

Get a verse by chapterNo and verseNo

import { Quran } from 'islam.js';
const quran = new Quran();
const verse = quran.getVerse(21, 107);
console.log(verse);

//Output
'وَمَا أَرْسَلْنَاكَ إِلَّا رَحْمَةً لِّلْعَالَمِينَ'

Get multiple verses with translation

import { Quran } from 'islam.js';
const quran = new Quran();
const verse =  quran.getMultipleVersesWithTranslation([{ chapterNo: 21, verseNo: 107 }]);
console.log(verse);

//Output
[
   {
      "verse": "وَمَا أَرْسَلْنَاكَ إِلَّا رَحْمَةً لِّلْعَالَمِينَ",
      "translation": "And We have not sent you, [O Muhammad], except as a mercy to the worlds."
   }
]

We can specify a different language for translation as well.

import { Quran, TranslationEnum } from 'islam.js';
const quran = new Quran();
const verse =  quran.getMultipleVersesWithTranslation([{ chapterNo: 21, verseNo: 107 }], TranslationEnum.French);
console.log(verse);

//Output
[
   {
      "verse": "وَمَا أَرْسَلْنَاكَ إِلَّا رَحْمَةً لِّلْعَالَمِينَ",
      "translation": "Et Nous ne t'avons envoyé qu'en miséricorde pour l'univers."
   }
]

Get random verse with translation

import { Quran } from 'islam.js';
const quran = new Quran();
const verse =  quran.getRandomVerseWithTranslation();
console.log(verse);

//Output
{
   "chapter": "الزمر",
   "verseNo": 53,
   "verse": "۞ قُلْ يَا عِبَادِيَ الَّذِينَ أَسْرَفُوا عَلَىٰ أَنفُسِهِمْ لَا تَقْنَطُوا مِن رَّحْمَةِ اللَّهِ ۚ إِنَّ اللَّهَ يَغْفِرُ الذُّنُوبَ جَمِيعًا ۚ إِنَّهُ هُوَ الْغَفُورُ الرَّحِيمُ",
   "translation": "Say, 'O My servants who have transgressed against themselves [by sinning], do not despair of the mercy of Allah.Indeed, Allah forgives all sins. Indeed, it is He who is the Forgiving, the Merciful.'"
}

Get a verse with translation and tafseer

import { Quran, TranslationEnum, TafseerEnum } from 'islam.js';
const quran = new Quran();
const verse = await quran.getVerseWithTranslationAndTafseer(53, 39, TranslationEnum.Urdu, TafseerEnum.TafsirBayanulQuran)
console.log(verse);

//Output
{
   "verse": "وَأَن لَّيْسَ لِلْإِنسَانِ إِلَّا مَا سَعَىٰ",
   "translation": "اور یہ کہ انسان کو وہی ملتا ہے جس کی وہ کوشش کرتا ہے",
   "tafseer": "آیت 39{ وَاَنْ لَّــیْسَ لِلْاِنْسَانِ اِلَّا مَا سَعٰی۔ } ”اور یہ کہ انسان کے لیے نہیں ہے مگر وہی کچھ جس کی اس نے سعی کی ہوگی۔“ انسان کو جو کچھ کرنا ہوگا اپنی محنت اور کوشش کے بل پر کرنا ہوگا ‘ خواہشوں اور تمنائوں سے کچھ نہیں ہوگا۔ قبل ازیں آیت 24 میں سوال کیا گیا تھا کہ ”کیا انسان کو وہی کچھ مل جائے گا جس کی وہ تمنا کرے گا ؟“ یہ آیت گویا مذکورہ سوال کا جواب ہے۔"
}

2. Hadith

Get a hadith by book and hadithNo

import { Hadith, HadithBook } from 'islam.js';
const hadith = new Hadith();
const engHadith =  await hadith.getHadith(HadithBook.AbuDawud, 7)
console.log(engHadith);

//Output
{
   "metadata": {
      "name": "Sunan Abu Dawud",
      "section": "Purification (Kitab Al-Taharah)",
      "sectionDetails": {
        "arabicNumberFirst": 1,
        "arabicNumberLast": 390,
        "hadithNumberFirst": 1,
        "hadithNumberLast": 390
       }
   },
   "hadith": {

        "text": "Narrated Salman al-Farsi: It was said to Salman: Your Prophet teaches you everything, even about excrement. He replied: Yes. He has forbidden us to face the qiblah at the time of easing or urinating, and cleansing with right hand, and cleansing with less than three stones, or cleansing with dung or bone",
        "hadithNumber": 7,
        "arabicNumber": 7,
        "grades": [
            {
                "name": "Al-Albani",
                "grade": "Sahih"
            },
            {
                "name": "Muhammad Muhyi Al-Din Abdul Hamid",
                "grade": "Sahih"
            },
            {
                "name": "Shuaib Al Arnaut",
                "grade": "Sahih"
            },
            {
                "name": "Zubair Ali Zai",
                "grade": "Sahih Muslim (262)"
            }
        ]
   }
}

Get a complete section from a book by sectionNo

By default the language will be English but We can specify a different language as well.

import { Hadith, HadithBook, HadithLangEnum } from 'islam.js';
const hadith = new Hadith();
const section =  await hadith.getSection(HadithBook.Bukhari, 6, HadithLangEnum.Russian);
console.log(section);

//Output
{
   "metadata": {
      "name":"Sahih al Bukhari",
      "section":"Menstrual Periods",
      "sectionDetails":{
            "arabicNumberFirst":294,
            "arabicNumberLast":333,
            "hadithNumberFirst":294,
            "hadithNumberLast":333
       }
   },
   "hadiths":[
        {
            "arabicNumber": 294,
            "grades": [],
            "hadithNumber": 294,
            "reference": { "book": 6, "hadith": 1 },
            "text": "Сообщается, что ‘Аиша, да будет доволен ею Аллах, сказала: «Мы покинули (Медину) с единственной целью совершить хаджж, а в Сарифе, у меня начались месячные. Зайдя ко мне, Посланник Аллаха ﷺ (увидел, что) я плачу, и спросил: “Что с тобой? У тебя начались месячные?” Я ответила: “Да”. Тогда он сказал: “Поистине, это предопределено Аллахом дочерям Адама. Совершай же всё, что совершает паломник, но только не обходи Дом (Каабу)!”»\\n(‘Аиша) сказала: «И Посланник Аллаха ﷺ принёс в жертву коров за своих жён»"
        },
        ...
        ...
        ...
   ]
}

3. Dua & Azkar

Get a random supplication

import { Azkar } from 'islam.js';
const azkar = new Azkar();
const supplication = azkar.getRandom();
console.log(supplication);

//Output
{
   "id":2669,
   "description":{
      
   },
   "count":"",
   "zikr":"((يُصَلِّي عَلَى النَّبِيِّ صلى الله عليه وسلم بَعْدَ فَرَاغِهِ مِنْ إِجَابَةِ الْمُؤَذِّنِ)).",
   "reference":"",
   "category":"أذكار الآذان"
}

Get a random supplication by category

import { Azkar } from 'islam.js';
const azkar = new Azkar();
const supplication = azkar.getRandomByCategory(AzkarCategoriesEnum.Anxiety);
console.log(supplication);

//Output
{
   "id":809,
   "description":{},
   "count":"",
   "zikr":"((اللَّهُمَّ إِنِّي أَعُوذُ بِكَ مِنَ الْهَمِّ وَالْحَزَنِ، وَالْعَجْزِ وَالْكَسَلِ، وَالْبُخْلِ وَالْجُبْنِ، وَضَلَعِ الدَّيْنِ وَغَلَبَةِ الرِّجَالِ)).",
   "reference":"",
   "category":"دعاء الهم والحزن"
}

Get all supplications by category

import { Azkar } from 'islam.js';
const azkar = new Azkar();
const supplication = azkar.getByCategory(AzkarCategoriesEnum.Morning);
console.log(supplication);

//Output
[
   {
      "id":2338,
      "description":{},
      "count":"3",
      "zikr":"سُبْحـانَ اللهِ وَبِحَمْـدِهِ عَدَدَ خَلْـقِه ، وَرِضـا نَفْسِـه ، وَزِنَـةَ عَـرْشِـه ، وَمِـدادَ كَلِمـاتِـه.",
      "reference":"مسلم",
      "category":"أذكار الصباح"
   },
   ...
   ...
   ...
]

Get all supplications

import { Azkar } from 'islam.js';
const azkar = new Azkar();
const supplication = azkar.getAll();
console.log(supplication);

//Output
[
    {
    "category":"أذكار الصباح",
    "count":"1",
    "description":{},
    "id":2374,
    "reference":"أحمد",
    "zikr":"أَصْبَـحْـنا عَلَى فِطْرَةِ الإسْلاَمِ، وَعَلَى كَلِمَةِ الإِخْلاَصِ، وَعَلَى دِينِ نَبِيِّنَا مُحَمَّدٍ صَلَّى اللهُ عَلَيْهِ وَسَلَّمَ، وَعَلَى مِلَّةِ أَبِينَا إبْرَاهِيمَ حَنِيفاً مُسْلِماً وَمَا كَانَ مِنَ المُشْرِكِينَ."
    },
    ...
    ...
    ...
]

4. Prayer Timings

Get prayer timing by location

import { Prayer } from 'islam.js';
const prayer = new Prayer();
const date = '30-08-2024';
const latitude = 31.52037;
const longitude = 74.358749;

const prayerTimings = await prayer.getPrayerTimesByLocation(date, latitude, longitude);
console.log(prayerTimings);

//Output
{
  Fajr: "04:13",
  Sunrise: "05:37",
  Dhuhr: "12:03",
  Asr: "15:40",
  Sunset: "18:29",
  Maghrib: "18:29",
  Isha: "19:53",
  Imsak: "04:03",
  Midnight: "00:03",
  Firstthird: "22:11",
  Lastthird: "01:54",
}

Get prayer timing by city

import { Prayer } from 'islam.js';
const prayer = new Prayer();
const city = 'Dubai';
const country = 'United Arab Emirates';
const prayerTimings = await prayer.getPrayerTimesByCity(city, country)
console.log(prayerTimings);

//Output
{
  Fajr: "04:40",
  Sunrise: "05:59",
  Dhuhr: "12:22",
  Asr: "15:49",
  Sunset: "18:42",
  Maghrib: "18:42",
  Isha: "19:59",
  Imsak: "04:30",
  Midnight: "00:19",
  Firstthird: "22:26",
  Lastthird: "02:12",
}

5. Hijri Calander

Get hijri calander date by location

import { HijriCalendar } from 'islam.js';
const calender = new HijriCalendar();
const date = '30-08-2024';
const latitude = 31.52037;
const longitude = 74.358749;
const hijriDate = await calander.getHijriDateByLocation(date, latitude, longitude)
console.log(hijriDate);

//Output
{
   "date":"24-02-1446",
   "format":"DD-MM-YYYY",
   "day":"24",
   "weekday":{
      "en":"Al Juma'a",
      "ar":"الجمعة"
   },
   "month":{
      "number":2,
      "en":"Ṣafar",
      "ar":"صَفَر"
   },
   "year":"1446",
   "designation":{
      "abbreviated":"AH",
      "expanded":"Anno Hegirae"
   },
   "holidays":[]
}

Get hijri calander date by city

import { HijriCalendar } from 'islam.js';
const calender = new HijriCalendar();
const city = 'Dubai';
const country = 'United Arab Emirates';
const hijriDate = await calander.getHijriDateByCity(city, country);
console.log(hijriDate);

//Output
{
   "date":"24-02-1446",
   "format":"DD-MM-YYYY",
   "day":"24",
   "weekday":{
      "en":"Al Juma'a",
      "ar":"الجمعة"
   },
   "month":{
      "number":2,
      "en":"Ṣafar",
      "ar":"صَفَر"
   },
   "year":"1446",
   "designation":{
      "abbreviated":"AH",
      "expanded":"Anno Hegirae"
   },
   "holidays":[]
}

Disclaimer

islam.js is an open-source package created to provide easy access to various Islamic resources such as Quran, Hadith, Dua, and Azkar. This package is not an authoritative source on Islam and should not be taken as a definitive representation of the religion.

I have made every effort to use authentic sources, but as with any human endeavor, there may be mistakes or inaccuracies. Users are encouraged to consult scholars or authentic religious sources for comprehensive understanding and verification.

By using this package, you acknowledge that it is provided as-is, and you agree to use it responsibly.

License

This package is freely available for everyone to use. If you find it beneficial, please remember me in your prayers.
May Allah forgive my sins and have mercy on all of us. Ameen.

Contact

If you have any questions, suggestions, or would like to collaborate, please feel free to reach out:

Email: ahmadbilal.3491@gmail.com
LinkedIn: Ahmad Bilal
Website: Ahmad Bilal

I look forward to hearing from you!

Credits

This package utilizes the following resources:

Quran and Translations: Surah Quran, Kaggle Datset
Tafseer (Commentaries): Tafsir API by spa5k
Hadith Collections: Hadith API by fawazahmed
Hijri Calendar and Prayer Times: Aladhan Prayer Times API

I am grateful to these resources for making their data available for public use.

Name		Name	Last commit message	Last commit date
Latest commit History 118 Commits
.github		.github
.husky		.husky
scripts		scripts
src		src
test		test
.babelrc		.babelrc
.gitignore		.gitignore
.prettierrc		.prettierrc
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
commitlint.config.js		commitlint.config.js
eslint.config.mjs		eslint.config.mjs
islam.js-horizontal.png		islam.js-horizontal.png
islam.js-vertical.png		islam.js-vertical.png
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

islam.js

Features

Installation

Getting Started

Usage

1. Quran

Supported Translation Languages

Get a chapter by index

Get a chapter by name

Get a verse by chapterNo and verseNo

Get multiple verses with translation

Get random verse with translation

Get a verse with translation and tafseer

2. Hadith

Get a hadith by book and hadithNo

Get a complete section from a book by sectionNo

3. Dua & Azkar

Get a random supplication

Get a random supplication by category

Get all supplications by category

Get all supplications

4. Prayer Timings

Get prayer timing by location

Get prayer timing by city

5. Hijri Calander

Get hijri calander date by location

Get hijri calander date by city

Disclaimer

License

Contact

Credits

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Uh oh!

Contributors

Uh oh!

Languages