A comprehensive npm package for searching and browsing hadith collections with Arabic and English support. This package provides easy access to 16 major authentic hadith collections including Sahih al-Bukhari, Sahih Muslim, Sunan an-Nasa'i, and many more.
✨ Features both a powerful library API and an interactive CLI tool for different use cases - whether you're building applications or studying hadiths directly in the terminal.
Includes all the essential hadith collections: Sahih al-Bukhari, Sahih Muslim, the six canonical collections (Kutub al-Sittah), Musnad Ahmad, Riyad as-Salihin, and more.
npm install hadith
The package includes a hadith-cli binary for interactive terminal usage:
# If installed locally
npx hadith-cli
# Run the CLI directly
node node_modules/hadith/cli.js
# Or install globally for the hadith-cli command
npm install -g hadith
hadith-cli
data/hadith.db)const HadithDB = require('hadith');
async function example() {
// Initialize the database
const hadithDb = new HadithDB();
await hadithDb.connect();
try {
// Get all collections (16 available)
const collections = await hadithDb.getCollections();
console.log(`Available collections: ${collections.length}`);
// Search for hadiths about prayer
const searchResults = await hadithDb.search('prayer');
console.log(`Found ${searchResults.total} hadiths about prayer`);
// Get a random hadith
const randomHadith = await hadithDb.getRandomHadith();
console.log('Random hadith:', randomHadith.content);
// Get collection statistics
const stats = await hadithDb.getCollectionStats();
console.log(`Total hadiths: ${stats.total_hadiths}`);
} finally {
// Always close the connection
await hadithDb.close();
}
}
example().catch(console.error);
The package includes a powerful interactive CLI for browsing and studying hadiths directly in the terminal.
# Run directly from the package
node node_modules/hadith/cli.js
# Or if installed globally
hadith-cli
🌙 Welcome to Hadith CLI
═══════════════════════════════════════
? 📚 Select a hadith collection: Sahih al-Bukhari | صحيح البخاري
📖 Books in Sahih al-Bukhari:
──────────────────────────────────────────────────
? 📖 Select a book: Book 1: Revelation | كتاب بدء الوحى
📜 Hadiths displayed with full Arabic text, English translation,
narrator information, and metadata...
new HadithDB(dbPath?)Creates a new HadithDB instance.
dbPath (optional): Path to the SQLite database file. Defaults to the embedded databaseconst hadithDb = new HadithDB();
// or with custom path
const hadithDb = new HadithDB('/path/to/hadith.db');
getCollections(): Collection[]Returns all hadith collections.
const collections = hadithDb.getCollections();
collections.forEach(collection => {
console.log(`${collection.title_en} (${collection.title})`);
});
getCollection(collectionId): Collection | nullGet a specific collection by ID.
const bukhari = hadithDb.getCollection(1); // Sahih al-Bukhari
console.log(bukhari.title_en); // "Sahih al-Bukhari"
getCollectionStats(collectionId?): CollectionStatsGet statistics for a collection or overall database.
// Overall stats
const stats = hadithDb.getCollectionStats();
console.log(`Total collections: ${stats.collection_count}`);
// Collection-specific stats
const bukhariStats = hadithDb.getCollectionStats(1);
console.log(`Books in Bukhari: ${bukhariStats.book_count}`);
getBooks(collectionId): Book[]Get all books in a collection.
const books = hadithDb.getBooks(1); // Books in Sahih al-Bukhari
books.forEach(book => {
console.log(`${book.title_en} (${book.hadith_count} hadiths)`);
});
getBook(collectionId, bookId): Book | nullGet a specific book.
const book = hadithDb.getBook(1, 1); // First book of Bukhari
console.log(book.title_en); // "Revelation"
getChapters(collectionId, bookId): Chapter[]Get all chapters in a book.
const chapters = hadithDb.getChapters(1, 1); // Chapters in first book
chapters.forEach(chapter => {
console.log(chapter.title_en);
});
getChapter(collectionId, bookId, chapterId): Chapter | nullGet a specific chapter.
const chapter = hadithDb.getChapter(1, 1, 1);
console.log(chapter.title_en);
getHadithsByCollection(collectionId, options?): Hadith[]Get hadiths from a collection with optional filtering.
// Get first 10 hadiths from Bukhari
const hadiths = hadithDb.getHadithsByCollection(1, { limit: 10 });
// Get hadiths from specific book
const bookHadiths = hadithDb.getHadithsByCollection(1, {
bookId: 1,
limit: 5
});
// Get hadiths from specific chapter
const chapterHadiths = hadithDb.getHadithsByCollection(1, {
bookId: 1,
chapterId: 1,
limit: 3
});
getEnglishHadithsByCollection(collectionId, options?): EnglishHadith[]Get English translations of hadiths.
const englishHadiths = hadithDb.getEnglishHadithsByCollection(1, { limit: 10 });
englishHadiths.forEach(hadith => {
console.log(hadith.content);
});
getHadithByUrn(urn): Hadith | nullGet a specific hadith by its URN (Uniform Resource Name).
const hadith = hadithDb.getHadithByUrn('bukhari:1:1:1');
if (hadith) {
console.log(hadith.content);
}
getEnglishHadithByUrn(urn): EnglishHadith | nullGet English translation of a hadith by URN.
const englishHadith = hadithDb.getEnglishHadithByUrn('bukhari:1:1:1');
if (englishHadith) {
console.log(englishHadith.content);
}
getHadithByNumber(number): Hadith | nullSearch for a hadith by number across all collections. This method tries three search strategies in order:
// Find hadith 6689 (famous intentions hadith)
const hadith = await hadithDb.getHadithByNumber(6689);
if (hadith) {
console.log(`Found by: ${hadith.found_by}`); // "order_in_book"
console.log(`Collection: ${hadith.collection_id}`); // 1 (Al-Bukhari)
console.log(`Content: ${hadith.content}`);
}
// Search by display number
const hadith23 = await hadithDb.getHadithByNumber(23);
if (hadith23) {
console.log(`Found by: ${hadith23.found_by}`); // "display_number" or "order_in_book"
}
// Get first hadith from collection 2 (Sahih Muslim)
const muslimHadith = await hadithDb.getHadithByNumber(2);
if (muslimHadith) {
console.log(`Found by: ${muslimHadith.found_by}`); // "order_in_book" or "collection_id"
}
Note: The found_by field indicates which search method succeeded. Since order_in_book numbers are not globally unique across collections, this method returns the first match found.
searchArabic(query, options?): Hadith[]Search hadiths in Arabic.
// Basic search
const results = hadithDb.searchArabic('الصلاة');
// Search with options
const results = hadithDb.searchArabic('الصلاة', {
collectionId: 1, // Only in Bukhari
limit: 20,
searchInDiacless: true // Search without diacritics
});
searchEnglish(query, options?): EnglishHadith[]Search hadiths in English.
const results = hadithDb.searchEnglish('prayer', {
collectionId: 1,
limit: 10
});
search(query, options?): SearchResultsSearch in both Arabic and English.
const results = hadithDb.search('prayer');
console.log(`Arabic results: ${results.arabic.length}`);
console.log(`English results: ${results.english.length}`);
console.log(`Total: ${results.total}`);
getRandomHadith(collectionId?): Hadith | nullGet a random hadith.
// Random hadith from any collection
const randomHadith = hadithDb.getRandomHadith();
// Random hadith from specific collection
const randomBukhari = hadithDb.getRandomHadith(1);
getScholars(): Scholar[]Get information about hadith scholars.
const scholars = hadithDb.getScholars();
scholars.forEach(scholar => {
console.log(`${scholar.famous_name} (${scholar.born_on} - ${scholar.died_on})`);
});
getInfo(): DatabaseInfoGet database information and statistics.
const info = hadithDb.getInfo();
console.log(`Database version: ${info.version}`);
console.log(`Available collections: ${info.collections.length}`);
close(): voidClose the database connection.
hadithDb.close(); // Always close when done
const HadithDB = require('hadith');
const hadithDb = new HadithDB();
// Search for hadiths about charity
const results = hadithDb.search('charity');
console.log(`Found ${results.total} hadiths about charity:`);
console.log(`- ${results.arabic.length} in Arabic`);
console.log(`- ${results.english.length} in English`);
// Display first English result
if (results.english.length > 0) {
const hadith = results.english[0];
console.log(`\nHadith: ${hadith.content}`);
console.log(`Reference: ${hadith.reference}`);
}
hadithDb.close();
const HadithDB = require('hadith');
const hadithDb = new HadithDB();
// Get all collections
const collections = hadithDb.getCollections();
collections.forEach(collection => {
console.log(`\n${collection.title_en} (${collection.title})`);
console.log(`Status: ${collection.status}`);
// Get books in this collection
const books = hadithDb.getBooks(collection.id);
console.log(`Books: ${books.length}`);
// Get first few hadiths
const hadiths = hadithDb.getHadithsByCollection(collection.id, { limit: 3 });
console.log(`Sample hadiths: ${hadiths.length}`);
});
hadithDb.close();
const HadithDB = require('hadith');
const hadithDb = new HadithDB();
function getDailyHadith() {
const hadith = hadithDb.getRandomHadith();
const englishHadith = hadithDb.getEnglishHadithByUrn(hadith.urn);
return {
arabic: hadith.content,
english: englishHadith ? englishHadith.content : null,
reference: hadith.urn,
narrator: hadith.narrator_prefix
};
}
const daily = getDailyHadith();
console.log('Today\'s Hadith:');
console.log(`Arabic: ${daily.arabic}`);
if (daily.english) {
console.log(`English: ${daily.english}`);
}
console.log(`Reference: ${daily.reference}`);
hadithDb.close();
const HadithDB = require('hadith');
const hadithDb = new HadithDB();
async function findSpecificHadith() {
// Find the famous intentions hadith (#6689)
const hadith = await hadithDb.getHadithByNumber(6689);
if (hadith) {
console.log(`Found by: ${hadith.found_by}`); // "order_in_book"
console.log(`URN: ${hadith.urn}`);
console.log(`Collection: ${hadith.collection_id}`); // 1 (Al-Bukhari)
// Get collection and book information
const collection = await hadithDb.getCollection(hadith.collection_id);
const book = await hadithDb.getBook(hadith.collection_id, hadith.book_id);
console.log(`\nCollection: ${collection.title_en}`);
console.log(`Book: ${book.title_en}`);
console.log(`Hadith #${hadith.display_number} in ${book.title_en}`);
console.log(`\nArabic: ${hadith.content}`);
// Get English translation
const englishHadith = await hadithDb.getEnglishHadithByUrn(hadith.urn);
if (englishHadith) {
console.log(`\nEnglish: ${englishHadith.content}`);
console.log(`Reference: ${englishHadith.reference}`);
}
} else {
console.log('Hadith not found');
}
}
findSpecificHadith()
.then(() => hadithDb.close())
.catch(console.error);
The package includes full TypeScript definitions:
import HadithDB, { Collection, Hadith, SearchResults } from 'hadith';
const hadithDb = new HadithDB();
const collections: Collection[] = hadithDb.getCollections();
const results: SearchResults = hadithDb.search('prayer');
const hadith: Hadith | null = hadithDb.getRandomHadith();
const specificHadith: Hadith | null = await hadithDb.getHadithByNumber(6689);
hadithDb.close();
The database includes 16 major authentic hadith collections with nearly complete English translations:
Use getCollections() to programmatically access all collection metadata.
close() when done to free resourcesContributions are welcome! Please feel free to submit a Pull Request.
MIT License - see LICENSE file for details.
For questions and support, please open an issue on GitHub.
FAQs
Searching and browsing hadith collections with Arabic and English support
We found that hadith demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Four npm packages disguised as cryptographic tools steal developer credentials and send them to attacker-controlled Telegram infrastructure.
Security News
Ruby maintainers from Bundler and rbenv teams are building rv to bring Python uv's speed and unified tooling approach to Ruby development.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.