Quran Developer Platform

Developer-first Quran dataset and API platform. Strict TypeScript, full offline support, REST + GraphQL API, 134 translations, word-by-word data, and a per-ayah scholarly knowledge base.

npm install @faha1999/al-quran-database

import { getSurah, getAyah, searchAyahs } from '@faha1999/al-quran-database';

// No server. No network. No .env file. Works immediately.
const fatiha = getSurah(1);
// → { id: 1, name_en: 'Al-Faatiha', ayahs: [...7 resolved ayahs...] }

const ayah = getAyah(1, 'en.sahih');
// → { text: 'بِسْمِ ٱللَّهِ ...', translation: 'In the name of Allah...' }

const results = searchAyahs('mercy');
// → { items: [...], meta: { total: 50, ... } }

The package ships its own data — no running server required. Four editions are bundled for instant offline use: en.sahih, en.yusufali, quran-simple-clean, and quran-uthmani. All 134 other editions are available via CDN (see CDN access below).

All functions below work with no network or server:

import {
  getSurah, // surah + all resolved ayahs
  getAyah, // single ayah with translation + knowledge
  getAyahByNumber, // ayah by global number (1–6236)
  getAllSurahs, // all 114 surahs (paginatable)
  getJuzById, // juz with its ayahs
  getHizbById, // hizb with its ayahs
  getRubById, // rub with its ayahs
  getPageById, // Mushaf page with its ayahs
  searchAyahs, // full-text search (Arabic + translations)
  getReciters, // reciter list
  getDuas, // duas from Quran
  getKnowledgeByAyah, // per-ayah scholarly entry
  getKnowledgeFaqs, // FAQ knowledge base
  getDatasetMetadata, // dataset provenance info
  // Raw data
  surahs,
  ayahs,
  editions,
  juzs,
  hizbs,
  rubs,
  pages,
  BUNDLED_EDITION_IDENTIFIERS, // ['en.sahih', 'en.yusufali', ...]
} from '@faha1999/al-quran-database';

import { BUNDLED_EDITION_IDENTIFIERS, getSurah } from '@faha1999/al-quran-database';
console.log(BUNDLED_EDITION_IDENTIFIERS);
// → ['en.sahih', 'quran-simple-clean', 'en.yusufali', 'quran-uthmani']

const surahWithArabic = getSurah(2, 'quran-uthmani');
const surahWithEnglish = getSurah(2, 'en.sahih');

Served directly from the GitHub repository via jsDelivr — no signup, no config, CORS enabled, globally cached:

Base URL: https://cdn.jsdelivr.net/gh/faha1999/al-quran-database@{tag}/{path}

<!-- Fetch in JS -->
const res = await
fetch('https://cdn.jsdelivr.net/gh/faha1999/al-quran-database@v2.2.0/lib/data/surahs.json'); const
surahs = await res.json();

Available data files on CDN:

Pin to a specific release tag (e.g. @v2.2.0) for production. Use @main for the latest commit.

For applications that need all 134 editions, advanced search, or real-time features, run the full platform locally or deploy it yourself:

git clone https://github.com/faha1999/al-quran-database
npm install
npm run dev

import { QuranDevSDK } from '@faha1999/al-quran-database';

const sdk = new QuranDevSDK({ baseUrl: 'http://localhost:3000' });
const result = await sdk.getSurah(2, 'ur.maududi'); // any of 134 editions
const search = await sdk.search('mercy', { language: 'ur' });

Open locally:

• Docs: http://localhost:3000/docs
• Search UI: http://localhost:3000/search
• REST example: http://localhost:3000/api/v1/search?q=mercy&language=en
• GraphQL: POST /api/v1/graphql

• Zero-dependency offline data layer with 20+ typed functions
• Clean REST API for surahs, ayahs, juz, hizb, rub, pages, words, duas, reciters, and search
• Versioned REST under /api/v1/* plus legacy /api/* aliases
• GraphQL endpoint for flexible multi-entity queries
• Sharded JSON architecture for fast local reads and edge-friendly deployment
• Canonical JSON-first workflow: quran.sql stays local, committed data lives in lib/data/*
• Deterministic SQL → JSON verification with source SHA-256 metadata
• Normalized PostgreSQL + SQLite exports including knowledge/context tables
• Optional Redis cache layer with in-memory fallback for hot API routes
• Publishable JS/TS SDK: @faha1999/al-quran-database
• Search UI with composable edition and language filters
• SQL conversion, migration, export, validation, and performance scripts

• Next.js 16 · React 19 · TypeScript strict mode
• Tailwind CSS v4 · FlexSearch · Vitest · Playwright · ESLint + Prettier

npm run lint
npm run typecheck
npm test
npm run test:e2e
npm run build
npm run verify:sdk

Data pipeline:

npm run data:convert
npm run data:verify -- --check-determinism
npm run data:export
npm run data:migrate
npm run data:seed
npm run data:bench

• quran.sql is local-only and ignored by Git (source dump too large for repo workflows).
• lib/data/* is the committed source-of-truth.
• scripts/convert_quran_sql.py derives JSON, sharded edition payloads, groupings, and metadata.
• scripts/verify_quran_data.py proves row counts, shard integrity, and deterministic rebuilds.
• scripts/export_sql.py regenerates downloadable PostgreSQL and SQLite artifacts.

• Versioned REST lives under /api/v1/*.
• Legacy /api/* aliases remain for backward compatibility.
• Official hosted domain al-quran-database.vercel.app is a docs/showcase site only — API traffic is disabled. Use local or self-hosted deployments for runtime access.
• GraphQL supports composing surah, ayah, search, faqs, knowledge, and meta.
• Search accepts either edition or language; sending both returns a validation error.
• Set REDIS_URL to enable shared cache. Without it, in-memory cache still accelerates hot reads.

• Product docs UI: app/docs/*
• SDK package source: packages/sdk
• Repo docs: docs/api-reference.md, docs/sdk-guide.md, docs/architecture.md, docs/frontend-guide.md
• Live docs: https://al-quran-database.vercel.app/docs

• All API routes return { success, data?, error?, meta? }
• Shared route helpers centralize validation and error logging
• CI runs format check, lint, typecheck, unit/integration tests, SDK build/pack, e2e smoke tests, build
• PR template + CODEOWNERS support review discipline before merge

• SDK npm releases are published from main by GitHub Actions.
• Qualifying main branch changes auto-bump the next patch version from the npm registry state.
• Current public exports: QuranDevSDK, quran, getSurah, getAyah, searchAyahs, and all local data functions — plus all TypeScript types.

If this project saves you time or powers your app, consider sponsoring on GitHub. Every star and share also helps new developers discover it. ⭐

• Repository: https://github.com/faha1999/al-quran-database
• npm: https://www.npmjs.com/package/@faha1999/al-quran-database
• Docs: https://al-quran-database.vercel.app/docs
• CHANGELOG: CHANGELOG.md

MIT. See LICENSE.