@muslims-community/quran

A simple, lightweight, and offline Quran data package for JavaScript applications.

Features

• 🚀 Zero dependencies - No external dependencies required
• 📱 Universal - Works in Node.js, browsers, React, Vue, React Native, and more
• 🌐 Offline-first - Complete Quran text included in the package
• 📖 Complete - All 114 surahs with 6,236 ayat
• 🔍 Searchable - Built-in text search functionality
• 📚 Authentic - Based on official Tanzil Project Uthmani minimal text
• 🧩 TypeScript - Full TypeScript support with detailed type definitions
• 🎯 Tree-shakable - ES modules support for optimal bundle sizes

Installation

npm install @muslims-community/quran

Quick Start

CommonJS (Node.js)

const { getAyah, getSurah } = require('@muslims-community/quran');

// Get a specific ayah
const ayah = getAyah(1, 1); // Al-Fatiha, first ayah
console.log(ayah.text); // "بِسمِ اللَّهِ الرَّحمٰنِ الرَّحيمِ"

// Get a complete surah
const surah = getSurah(18); // Al-Kahf
console.log(surah.name); // "الكهف"
console.log(surah.englishName); // "Al-Kahf"
console.log(surah.numberOfAyahs); // 110

ES Modules (Modern JavaScript)

import { getAyah, getSurah, searchText, getJuz, getAyahRange } from '@muslims-community/quran';

// Get random ayah
import { getRandomAyah } from '@muslims-community/quran';
const randomAyah = getRandomAyah();
console.log(randomAyah.text);

// Get a range of ayat
const range = getAyahRange(2, 1, 5); // Al-Baqarah 1-5
console.log(`Reading ${range.range.count} ayat from ${range.surah.englishName}`);

// Get complete Juz for daily reading
const juz1 = getJuz(1);
console.log(`Juz 1 contains ${juz1.totalAyat} ayat`);

// Search for text
const results = searchText('الله');
console.log(`Found ${results.totalResults} ayat containing "الله"`);

TypeScript

import { getAyah, Surah, AyahWithSurah } from '@muslims-community/quran';

const ayah: AyahWithSurah = getAyah(2, 255); // Ayat al-Kursi
const surah: Surah = getSurah(112); // Al-Ikhlas

API Reference

getAyah(surahId: number, ayahId: number): AyahWithSurah

Retrieves a specific ayah from the Quran.

Parameters:

• surahId (1-114): The surah number
• ayahId (1-n): The ayah number within the surah

Returns:

{
  id: 1,
  text: "بِسمِ اللَّهِ الرَّحمٰنِ الرَّحيمِ",
  sajdah: false,
  surah: {
    id: 1,
    name: "الفاتحة",
    englishName: "Al-Fatiha",
    revelationType: "Meccan"
  },
  source: "Tanzil Project - https://tanzil.net"
}

getSurah(surahId: number): Surah

Retrieves a complete surah with all its ayat.

Parameters:

• surahId (1-114): The surah number

Returns:

{
  id: 1,
  name: "الفاتحة",
  englishName: "Al-Fatiha",
  revelationType: "Meccan",
  numberOfAyahs: 7,
  ayat: [
    { id: 1, text: "بِسمِ اللَّهِ الرَّحمٰنِ الرَّحيمِ", sajdah: false },
    // ... more ayat
  ],
  source: "Tanzil Project - https://tanzil.net"
}

searchText(searchTerm: string): SearchResult

Searches for Arabic text within the Quran.

Parameters:

• searchTerm: Arabic text to search for

Returns:

{
  results: [
    {
      id: 1,
      text: "بِسمِ اللَّهِ الرَّحمٰنِ الرَّحيمِ",
      sajdah: false,
      surah: { id: 1, name: "الفاتحة", englishName: "Al-Fatiha", revelationType: "Meccan" }
    }
    // ... more results
  ],
  searchTerm: "الله",
  totalResults: 2699,
  source: "Tanzil Project - https://tanzil.net"
}

getRandomAyah(): AyahWithSurah

Returns a random ayah from the Quran.

getSajdahAyat(): SajdahResult

Returns all ayat where sajdah (prostration) is recommended.

getQuranData(): QuranData

Returns the complete Quran dataset.

🚀 Enhanced Functions (v1.1.0)

getAyahRange(surahId: number, startAyah: number, endAyah: number): AyahRange

Get a range of ayat from a specific surah - perfect for reading applications.

Parameters:

• surahId (1-114): The surah number
• startAyah: Starting ayah number
• endAyah: Ending ayah number

Returns:

{
  surah: { id: 2, name: "البقرة", englishName: "Al-Baqarah", revelationType: "Medinan" },
  range: { start: 1, end: 5, count: 5 },
  ayat: [
    { id: 1, text: "الم", juz: 1, hizb: 1, sajdah: false },
    // ... more ayat
  ],
  source: "Tanzil Project - https://tanzil.net"
}

getJuz(juzNumber: number): JuzResult

Get all ayat from a specific Juz (Para) - essential for daily reading schedules.

Parameters:

• juzNumber (1-30): The Juz number

Returns:

{
  juz: 1,
  totalAyat: 148,
  ayat: [ /* all ayat in Juz 1 */ ],
  source: "Tanzil Project - https://tanzil.net"
}

getHizb(hizbNumber: number): HizbResult

Get all ayat from a specific Hizb - for precise reading portions.

Parameters:

• hizbNumber (1-60): The Hizb number

Returns:

{
  hizb: 1,
  juz: 1,
  totalAyat: 74,
  ayat: [ /* all ayat in Hizb 1 */ ],
  source: "Tanzil Project - https://tanzil.net"
}

searchBySurahName(name: string): SurahSearchResult

Search for surahs by Arabic or English name.

Parameters:

• name: Surah name to search for (supports partial matching)

Returns:

{
  searchTerm: "Fatiha",
  totalResults: 1,
  results: [
    {
      id: 1,
      name: "الفاتحة",
      englishName: "Al-Fatiha",
      revelationType: "Meccan",
      numberOfAyahs: 7,
      // ... complete surah data
    }
  ],
  source: "Tanzil Project - https://tanzil.net"
}

getSurahStatistics(): SurahStatistics

Get comprehensive statistics about the Quran - perfect for educational apps.

Returns:

{
  totalSurahs: 114,
  totalAyat: 6236,
  meccanSurahs: 86,
  medinanSurahs: 28,
  averageAyatPerSurah: 54.7,
  longestSurah: { id: 2, name: "البقرة", englishName: "Al-Baqarah", numberOfAyahs: 286 },
  shortestSurah: { id: 103, name: "العصر", englishName: "Al-'Asr", numberOfAyahs: 3 },
  ayatCounts: {
    min: 3,
    max: 286,
    distribution: { 3: 1, 4: 2, 5: 2, /* ... */ }
  },
  source: "Tanzil Project - https://tanzil.net"
}

Usage Examples

React Component

import React, { useState, useEffect } from 'react';
import { getRandomAyah } from '@muslims-community/quran';

function DailyAyah() {
  const [ayah, setAyah] = useState(null);

  useEffect(() => {
    setAyah(getRandomAyah());
  }, []);

  if (!ayah) return <div>Loading...</div>;

  return (
    <div className="daily-ayah">
      <p className="arabic-text">{ayah.text}</p>
      <p className="surah-info">
        {ayah.surah.englishName} ({ayah.surah.name}) - Ayah {ayah.id}
      </p>
      <small>{ayah.source}</small>
    </div>
  );
}

Search Implementation

import { searchText } from '@muslims-community/quran';

function searchQuran(query) {
  try {
    const results = searchText(query);
    console.log(`Found ${results.totalResults} results for "${query}"`);

    results.results.forEach(ayah => {
      console.log(`${ayah.surah.englishName} ${ayah.id}: ${ayah.text}`);
    });
  } catch (error) {
    console.error('Search error:', error.message);
  }
}

searchQuran('الرحمن'); // Search for "Ar-Rahman"

Sajdah Ayat

import { getSajdahAyat } from '@muslims-community/quran';

const sajdahVerses = getSajdahAyat();
console.log(`Total sajdah ayat: ${sajdahVerses.totalSajdahAyat}`);

sajdahVerses.sajdahAyat.forEach(ayah => {
  console.log(`${ayah.surah.englishName} ${ayah.id}: ${ayah.text}`);
});

Daily Juz Reading App

import { getJuz, getSurahStatistics } from '@muslims-community/quran';

function createReadingPlan() {
  const stats = getSurahStatistics();
  console.log(`📖 Complete Quran: ${stats.totalAyat} ayat in ${stats.totalSurahs} surahs`);

  // 30-day reading plan
  for (let day = 1; day <= 30; day++) {
    const juz = getJuz(day);
    console.log(`Day ${day}: Juz ${juz.juz} - ${juz.totalAyat} ayat`);
  }
}

Range Reading for Study

import { getAyahRange, searchBySurahName } from '@muslims-community/quran';

// Find and read specific sections
const kahfSurah = searchBySurahName('Kahf').results[0];
const opening = getAyahRange(kahfSurah.id, 1, 10);

console.log(`Reading opening of ${opening.surah.englishName}:`);
opening.ayat.forEach((ayah, index) => {
  console.log(`${index + 1}. ${ayah.text}`);
});

Quran Statistics Dashboard

import { getSurahStatistics, getJuz, getHizb } from '@muslims-community/quran';

function generateDashboard() {
  const stats = getSurahStatistics();

  return {
    overview: {
      totalSurahs: stats.totalSurahs,
      totalAyat: stats.totalAyat,
      averageLength: stats.averageAyatPerSurah
    },
    breakdown: {
      meccan: stats.meccanSurahs,
      medinan: stats.medinanSurahs,
      longest: stats.longestSurah.englishName,
      shortest: stats.shortestSurah.englishName
    },
    reading: {
      juzCount: 30,
      hizbCount: 60,
      dailyAverage: Math.round(stats.totalAyat / 30)
    }
  };
}

Data Structure

The package includes complete Quranic text with the following metadata for each ayah:

• Arabic text (Uthmani script with minimal diacritics)
• Surah information (Arabic name, English name, revelation type)
• Sajdah markers (prostration verses)
• Bismillah markers (where applicable)

Text Source & License

Quran Text

• Source: Tanzil Project - Uthmani Minimal, Version 1.1
• License: Creative Commons Attribution 3.0
• Terms: The Quran text cannot be modified. Source attribution to Tanzil Project is required.

Package License

• License: MIT License
• Usage: Free for commercial and non-commercial use

Contributing

We welcome contributions! Please see our GitHub repository for:

• 🐛 Bug reports
• 💡 Feature requests
• 📖 Documentation improvements
• 🧪 Test additions

Support

• 📚 Documentation
• 🐛 Issues
• 💬 Discussions

Related Projects

This package serves as the foundational data layer for the Muslims Community ecosystem:

• 🌐 Quran API - RESTful API built on this package
• 📱 Mobile Apps - React Native applications
• 🖥️ Web Apps - Next.js and React applications

Made with ❤️ by Muslims Community

"And We have certainly made the Qur'an easy for remembrance, so is there any who will remember?" - Al-Qamar 54:17