hindu-devotional-texts

Typed, hand-curated Hindu devotional text — aartis, chalisas, kathas, mantras, stotras, ashtottaras (108-name) and sahasranamas (1000-name) litanies, Vedic sūktas, daily prayers, puja vidhi, Navratri, weekday (vaar) devatas, tīrtha (sacred-site) registries, the festival/ekādaśī calendar, and full scriptures (Bhagavad Gītā, Tulsidas's Rāmcharitmanas, Sundarkāṇḍ, and eight principal Upaniṣads) — as a zero-dependency npm package you can import into any Node, Next.js, or React Native project.

Why this exists

Most Hindu devotional content online is AI-generated or scraped-with-errors. For devotional verses, a single transposed character changes the meaning. This package is hand-typed / researched-and-verified and versioned in git, intended to be the authoritative reference itself — consumers don't need to cross-check anywhere else.

Status: Beta (0.7.x). The schema and getter API are stable; content is broad and growing, and most of it ships at draft pending a human verification pass against printed canonical editions. Pin exactly in your package.json until 1.0.0.

Install

npm install hindu-devotional-texts

Requires Node 20+ and ESM ("type": "module" in your package.json, or a bundler that handles ESM — Next.js, Vite, Metro, etc. all work out of the box). Zero runtime dependencies.

Quick start

import {
  getAarti,
  getChalisa,
  getKatha,
  getScripture,
  getMantra,
  getStotra,
  getAshtottara,
  getSahasranama,
  getSukta,
  getPrayer,
  getPuja,
  getFestival,
  getContentForDeity,
} from 'hindu-devotional-texts'

const hanumanAarti = getAarti('hanuman')
// { slug, deity, titleEnglish, titleHindi, verses: { english, hindi }, about }

const ramaChalisa = getChalisa('rama')
// { slug, deity, titleEnglish, titleHindi, openingDoha?, soratha?, chaupai, closingDoha?, about }

const satyanarayan = getKatha('satyanarayan')
// { slug, deity?, titleEnglish, titleHindi, about, samagri, vidhi, chapters }

const manas = getScripture('ramcharitmanas')
// { slug, titleEnglish, titleHindi, titleSanskrit?, deity?, chapters, about }

const tandava = getStotra('shiva-tandava-stotram')
// { slug, deity, titleEnglish, titleHindi, form, verses, about, reviewPending? }

const morningPrayer = getPrayer('karagre-vasate-lakshmi')
// { slug, occasion, titleEnglish, titleHindi, text: { devanagari, iast }, meaning, about }

const everythingForShiva = getContentForDeity('shiva')
// { aarti?, chalisa?, ashtottara?, sahasranama?, kathas, mantras, stotras, prayers, suktas }

Everything is fully typed, including the slug unions (so getKatha(' / getScripture(' / getStotra(' autocomplete to valid slugs):

import type {
  Recitation, Chalisa, Katha, Scripture, Stotra, Sukta, Sahasranama,
  Deity, KathaSlug, ScriptureSlug, StotraSlug, SuktaSlug,
} from 'hindu-devotional-texts'

API

All access goes through getter functions — the raw data maps are not exported, so underlying storage can evolve without breaking consumers.

Aartis & Chalisas (keyed by deity)

getAarti(deity: Deity): Recitation | undefined
getAllAartis(): Recitation[]

getChalisa(deity: Deity): Chalisa | undefined
getAllChalisas(): Chalisa[]

Kathas (keyed by slug)

Kathas are slug-keyed, not deity-keyed — one deity can have multiple kathas, and vrat kathas like Karva Chauth aren't tied to a single deity at all. KathaSlug is a string literal union, so your IDE autocompletes valid slugs.

getKatha(slug: KathaSlug): Katha
getAllKathas(): Katha[]
getKathasForDeity(deity: Deity): Katha[]

Scriptures (keyed by slug)

ScriptureSlug is a string literal union with IDE autocomplete. Eleven scriptures ship — the Bhagavad Gītā, Tulsidas's Rāmcharitmanas (all seven kāṇḍs) and its standalone Sundarkāṇḍ, and the eight principal Upaniṣads (Īśa, Kena, Māṇḍūkya, Kaṭha, Muṇḍaka, Praśna, Aitareya, Taittirīya). Each verse carries Devanagari plus, where present, IAST, an English rendering, and a Hindi meaning — see the populated table below for per-scripture coverage.

getScripture(slug: ScriptureSlug): Scripture
getAllScriptures(): Scripture[]

Mantras (keyed by slug)

Slug-keyed because canonical mantras like Gayatri and Maha Mrityunjaya aren't tied to a single deity. MantraSlug is a string literal union with IDE autocomplete; reverse lookup by deity covers the deity-tied ones.

getMantra(slug: MantraSlug): Mantra
getAllMantras(): Mantra[]
getMantrasForDeity(deity: Deity): Mantra[]

Stotras (keyed by slug)

Devotional hymns (Śiva Tāṇḍava, Mahiṣāsura-mardinī, Kanakadhāra, Bhaja Govindam, Rāma Rakṣā, the Hanuman set, and more). Each carries a form tag and parallel verses; StotraSlug is a string literal union. Reverse lookup matches the primary deity or any deity in the optional deities set.

getStotra(slug: StotraSlug): Stotra
getAllStotras(): Stotra[]
getStotrasForDeity(deity: Deity): Stotra[]

Ashtottara Shatanamavali (108 names, keyed by deity)

The standard 108-name litany recited at step 12 of Shodashopachara — one name per flower or akshat offering. Deity-keyed (one canonical ashtottara per deity). Returns undefined for two deities by design — vaishno-devi (the Vaishno Devi temple uses the Durga ashtottara; no independent canonical 108-list exists) and khatu-shyam (only ~40 epithets are preserved by tradition, no fixed-108 list).

getAshtottara(deity: Deity): Ashtottara | undefined
getAllAshtottaras(): Ashtottara[]

Each Ashtottara carries 108 archana lines in the recited form (ॐ … नमः), each with IAST — machine-generated from the Devanagari and round-trip-verified (the bar the Geeta IAST meets).

Sahasranama (1000 names, keyed by deity)

The 1000-name litanies — the Viṣṇu Sahasranāma and the Lalitā Sahasranāma — each shipping both the recited stotram (verse form) and the namavali (ॐ … नमः archana form).

getSahasranama(deity: Deity): Sahasranama | undefined
getAllSahasranamas(): Sahasranama[]

Vedic Sūktas (keyed by slug)

Six Vedic sūktas — Śrī Sūkta, Puruṣa Sūkta, Nārāyaṇa Sūkta, Durgā Sūkta, Mantra Puṣpam, and the Śrī Rudram. Each carries its vedicSource and is organised into sections. Because these are accented Vedic text, their IAST is an accent-stripped best-effort romanisation (not strict round-trip IAST). SuktaSlug is a string literal union; reverse lookup by deity is supported.

getSukta(slug: SuktaSlug): Sukta
getAllSuktas(): Sukta[]
getSuktasForDeity(deity: Deity): Sukta[]

Daily prayers / Nitya Karma (keyed by slug)

The everyday shlokas a home altar uses around the day's rhythm — kept in a dedicated prayers/ module (not the jaap mantras/ list). Each Prayer carries an occasion tag (morning · bath · meal · evening · night · invocation · closing), a single Devanagari + IAST block (round-trip-verified), and a bilingual meaning. Seven shipped: Karagre Vasate Lakshmi, Samudra Vasane Devi, Brahmarpanam (= Geeta 4.24 + 15.14), Shubham Karoti Kalyanam, Karacharana Kritam, Vakratunda Mahakaya, Tvameva Mata.

getPrayer(slug: PrayerSlug): Prayer
getAllPrayers(): Prayer[]
getPrayersForOccasion(occasion: PrayerOccasion): Prayer[]
getPrayersForDeity(deity: Deity): Prayer[]

Puja (keyed by slug)

Seven featured pujas, each parameterised on the 16-step Shodashopachara template with pre- and post-arcs. PujaSlug is a string literal union.

getPuja(slug: PujaSlug): Puja
getAllPujas(): Puja[]
getPujasForDeity(deity: Deity): Puja[]

PUJA_DISCLAIMER is exported alongside — the standard "regional and family variations exist; a pandit's guidance supersedes this" footnote each puja carries.

Navratri

The nine Navadurga forms (Day 1 → 9), the vrat-rule tiers and food lists, Kanya Pujan, and the Durga Saptashati 13-chapter outline. The per-day Navratri colour is computed by the consumer from the weekday Day 1 falls on — the library ships only the canonical weekday colour cycle and the rule, never a per-form colour.

getNavadurgaForm(day: 1|2|3|4|5|6|7|8|9): NavadurgaForm
getAllNavadurgaForms(): NavadurgaForm[]

navratriVratTiers      // VratTier[] — four fasting-intensity tiers
navratriVratFoods      // VratFoodList — allowed / forbidden lists
kanyaPujan             // KanyaPujanData — nine age-names + protocol
saptashatiOutline      // SaptashatiOutline — 13 chapters + nine-day reading map
navratriColourCycle    // NavratriColour[] — weekday → colour
navratriColourRule     // how the daily colour is derived

Vaar Devata (weekday-deity, keyed by date)

The seven weekday (vaara) entries, indexed by Date.getDay(). Each carries the ruling graha, presiding deities (all of equal standing — list order is not a ranking), ruling colour, top offerings, the weekday mantra, a fasting/vrat summary, and regional variant notes. VAAR_SOURCES is a plain disclaimer string (names no sources).

getVaarDevataForDate(d: Date): VaarDevata        // d.getDay()-indexed
getVaarDevataByKey(dayKey: string): VaarDevata | undefined
getVaarDevataByGraha(graha: GrahaKey): VaarDevata | undefined

VAAR_DEVATA            // readonly VaarDevata[] — the 7 weekday entries
VAAR_SOURCES           // Bilingual — a source-free practice disclaimer
vaarRosterIds(v)       // Deity[] — the day's roster-linked deities, de-duped
vaarDeityNames(v, lang)// string — the day's deity names joined for a label

Tīrtha (sacred-site registries)

Canonical pilgrimage groupings — the 12 Jyotirlingas, the 51/78 Shakti Peethas, the Char Dham and Chota Char Dham, the Sapta Puri, and the seven sacred rivers — each entry with its location and association, plus the traditional enumeration ślokas (Dvādaśa Jyotirliṅga Stotra, Sapta Purī, Sapta Nadī).

getJyotirlingas() · getShaktiPeethas() · getCharDham() · getChotaCharDham()
getSaptaPuri() · getSacredRivers() · getAllTirthas()
getTirtha(slug) · getTirthasForDeity(deity)

JYOTIRLINGAS · SHAKTI_PEETHAS · CHAR_DHAM · CHOTA_CHAR_DHAM · SAPTA_PURI
SACRED_RIVERS · DVADASHA_JYOTIRLINGA_STOTRA · SAPTA_PURI_SLOKA · SAPTA_NADI_SLOKA
TIRTHA_SOURCES

Festivals & Ekādaśī calendar (keyed by slug)

The festival registry — the 26 Ekādaśīs (each with its vrat story / scriptural origin), the tithi-vrats (Pradosha, Satyanarayan Purnima, …), and 31 major festivals (Diwali, Holi, Navratri, Janmashtami, …). Each carries its deity (or null), the lunar month/tithi where applicable, bilingual significance, and cross-links to related scriptures/mantras/kathas. No Gregorian dates or clock times — observance timing (panchang) is out of scope; the data names the tithi, never a date.

getFestival(slug): FestivalEntry | undefined
getAllFestivals(): FestivalEntry[]
getEkadashis(): FestivalEntry[]
getFestivalsByCategory(category: FestivalCategory): FestivalEntry[]   // 'ekadashi' | 'tithi-vrat' | 'festival'
getFestivalsForDeity(deity: Deity): FestivalEntry[]

EKADASHIS · FESTIVAL_SOURCES

Aggregate

getContentForDeity(deity: Deity): {
  aarti?: Recitation
  chalisa?: Chalisa
  ashtottara?: Ashtottara
  sahasranama?: Sahasranama
  kathas: Katha[]
  mantras: Mantra[]
  stotras: Stotra[]
  prayers: Prayer[]
  suktas: Sukta[]
}

Supported deities

The Deity type is a string union. In-scope deities (19):

ganesha, shiva, vishnu, hanuman, lakshmi, krishna, rama, durga,
saraswati, parvati, kali, surya, brahma, sai-baba, santoshi-mata,
sita, khatu-shyam, vaishno-devi, narasimha

Plus 'other' as a fallback bucket.

Types at a glance

interface Recitation {            // aartis
  slug: string
  deity: Deity
  titleEnglish: string
  titleHindi: string
  titleSanskrit?: string
  verses: {
    english: RecitationVerse[]    // Roman-script chant
    hindi: RecitationVerse[]      // Devanagari
  }
  about: { en: string; hi: string }
}

interface Scripture {
  slug: string
  titleEnglish: string
  titleHindi: string
  titleSanskrit?: string
  deity?: Deity
  chapters: Chapter[]               // each with { number, titleEnglish?, titleHindi?, titleSanskrit?, verses }
  about: { en: string; hi: string }
}

interface ScriptureVerse {
  devanagari: string                // required
  iast?: string                     // optional transliteration
  english?: string                  // optional English rendering
  hindi?: string                    // optional Hindi meaning / bhāvārtha
}

Source of truth: src/types.ts — also defines Chalisa, Katha, Mantra, Stotra, Sukta, Ashtottara, Sahasranama, Prayer, and the module-local types under each folder's types.ts.

What's currently populated

| Category | Scope | Populated | |---|---|---| | aartis | 19 deities | all 19 | | chalisas | 19 deities | all 19 | | kathas | 6 slugs | all 6 — satyanarayan + 5 vrat kathas (karva-chauth, vaibhav-lakshmi, santoshi-mata, solah-somvar, ahoi-ashtami); mahapuran-scale texts live under scriptures | | scriptures | 11 (2,250 verses) | see the breakdown below | | mantras | 21 jaap mantras | all 21; IAST round-trip-verified | | stotras | 13 | Śiva Tāṇḍava, Liṅgāṣṭakam, Bilvāṣṭakam, Madhurāṣṭakam, Achyutāṣṭakam, Mahālakṣmī Aṣṭakam, Mahiṣāsura-mardinī, Kanakadhāra, Bhaja Govindam, Rāma Rakṣā, Saṅkaṭ Mochan, Bajrang Bāṇ, Hanuman Bāhuk — researched draft | | ashtottara | 19 deities | 17 of 19 — every roster deity except vaishno-devi and khatu-shyam; all 1,836 names carry round-trip-verified IAST | | sahasranama | 2 | Viṣṇu Sahasranāma + Lalitā Sahasranāma (each: stotram + 1000-name namavali) — draft | | suktas | 6 Vedic | Śrī, Puruṣa, Nārāyaṇa, Durgā, Mantra Puṣpam, Śrī Rudram — accent-stripped best-effort IAST, draft | | prayers | 7 nitya-karma shlokas | all 7; IAST round-trip-verified, draft until a reviewer pass on the meanings | | puja | 7 featured pujas | all 7 (satyanarayan, lakshmi-diwali, ganesh, rudrabhishek, hanuman, navagraha, navratri-ghatasthapana) | | navratri | 9 forms, vrat tiers + foods, Kanya Pujan, Saptashati outline, colour cycle | all populated; Saptashati is outline-only | | vaar | 7 weekdays | all 7 — graha, deities, colour, offerings, mantra, fasting, variants; draft, mantras reviewPending | | tirtha | 112 entries | 12 Jyotirlingas · 78 Shakti Peethas · 4 Char Dham · 4 Chota Char Dham · 7 Sapta Puri · 7 sacred rivers, with enumeration ślokas | | festivals | 63 entries | 26 Ekādaśīs · 6 tithi-vrats · 31 festivals — deity, month/tithi, significance, cross-links; provisional (reviewPending) |

Scriptures breakdown

| Scripture | Scope | Layers | |---|---|---| | bhagavad-geeta | 18 ch / 701 verses | Devanagari + IAST + English (Purohit Swami, public domain) + Hindi bhāvārtha on every verse + per-chapter colophons | | ramcharitmanas | 7 kāṇḍ / 1,077 verses | Devanagari + best-effort Awadhi IAST on all verses. Researched English prose + Hindi bhāvārtha on Araṇya, Kiṣkindhā, Sundar (139 verses); the other four kāṇḍs (Bāla, Ayodhyā, Laṅkā, Uttara) are IAST-only for now, meaning layers landing kāṇḍ-by-kāṇḍ | | sundarkand | 1 ch / 63 verses | Devanagari (Awadhi) + best-effort romanization + researched English prose + Hindi bhāvārtha on all 63 (also reused as the Rāmcharitmanas's 5th kāṇḍ) | | 8 principal Upaniṣads | Īśa 19 · Kena 36 · Māṇḍūkya 13 · Kaṭha 121 · Muṇḍaka 65 · Praśna 68 · Aitareya 34 · Taittirīya 53 | clean Sanskrit — strict round-trip-verified IAST + English + Hindi on every verse |

Aarti/chalisa/ashtottara/sahasranama getters take a Deity and may return undefined — check before rendering. Katha/scripture/stotra/sukta/mantra/prayer/puja getters take a slug union whose values are guaranteed to exist in the registry, so they return non-nullable.

Content review debt

Most modules ship at draft and await a human verification pass against printed canonical editions before verified. The aartis and chalisas are hand-typed; the scriptures, stotras, suktas, sahasranamas, puja, navratri, vaar, tirtha, and festival modules are researched and cross-validated against the sources recorded in each module's SOURCES.md — not transcribed from a single canonical text.

• reviewPending: true is carried by every mantra in the puja/navratri modules, every Navadurga dhyana shloka, the vaar weekday mantras, the festival entries, and items in the stotra/sukta/sahasranama modules where the transliteration or prose meaning is still provisional. Consumers should surface a "transliteration / meaning under review — provisional" caption wherever a reviewPending item is displayed.
• Scriptures. The Geeta and the eight principal Upaniṣads carry strict, round-trip-verified IAST. The Awadhi Sundarkāṇḍ and Rāmcharitmanas carry a best-effort romanization (a pronunciation aid, not strict IAST — the retroflex flaps ड़/ढ़ have no IAST letter) and a researched English + Hindi (never a copied copyrighted translation). The Rāmcharitmanas meaning layer is still being filled in for four of its seven kāṇḍs; a few dense Awadhi segments are flagged in SOURCES.md for a human pass.
• Each module folder carries a SOURCES.md recording its citations, the disagreements found between sources, and the soft spots.

Rendering guidance

The package ships only data + typed getters — no React components, no CSS, no rendering helpers. Notes for consumers:

• Aartis / chalisas carry parallel english + hindi stanza arrays kept index-aligned. english[i] and hindi[i] are the same stanza in two scripts (both recitation text — English is Roman transliteration, not a translation). Render them side-by-side by index or toggle between them.
• Chalisas have up to four sections (openingDoha, soratha, chaupai, closingDoha) — render each only if present.
• Kathas render as: samagri.intro → samagri.items list → vidhi paragraphs → each chapter. Paragraphs may contain any combination of English prose, Hindi prose, and Sanskrit shlokas with IAST — render whichever fields are set.
• Scriptures have optional iast + english + hindi per verse — render whichever are present. The Geeta and Upaniṣads carry all layers; the Rāmcharitmanas carries IAST everywhere but English/Hindi only on the layered kāṇḍs (Araṇya, Kiṣkindhā, Sundar) — so design the verse view to degrade gracefully when english/hindi are absent. Geeta chapters also carry the traditional closing colophon.
• Titles are always bilingual (titleEnglish + titleHindi) — route on titleEnglish/slug, surface titleHindi in UI.
• Dates / panchang (when to observe a vrat, tithi-to-date calculations) are out of scope — the festival data names the tithi, never a Gregorian date.

Script policy

• Aartis and chalisas carry parallel Roman-script chant (english) and Devanagari (hindi) recitation texts. These are independent recitations, not translations of each other.
• Kathas allow any mix of English prose, Hindi (Devanagari), and Sanskrit shlokas with IAST transliteration.
• Scriptures, stotras, suktas, prayers use full IAST diacritics in iast fields. No ITRANS, no Harvard-Kyoto, no ad-hoc schemes. Clean-Sanskrit texts are round-trip-verified; Vedic-accented and Awadhi texts carry a documented best-effort romanization instead.

IAST reference (scriptures only)

| IAST | Devanagari | Notes | |---|---|---| | ā | आ | long a | | ī | ई | long i | | ū | ऊ | long u | | ṛ | ऋ | vocalic r | | ṝ | ॠ | long vocalic r | | ḷ | ऌ | vocalic l | | ṅ | ङ | velar nasal | | ñ | ञ | palatal nasal | | ṭ | ट | retroflex t | | ḍ | ड | retroflex d | | ṇ | ण | retroflex n | | ś | श | palatal sh | | ṣ | ष | retroflex sh | | ṃ | ं | anusvāra | | ḥ | ः | visarga |

Canonical forms inside transliterated lines: oṁ (not om/Om), śrī (not shree/shri/sri), kṛṣṇa (not krishna). Slugs stay English-friendly (krishna, not kṛṣṇa) for discoverability.

Guarantees

• Zero runtime dependencies.
• No AI-fabricated content. Every item is hand-verified or researched-and-cross-validated against canonical traditional text before it ships; provenance for the researched modules lives in each folder's SOURCES.md.
• No rendering baked in. Data + typed getters, nothing else — bring your own UI.
• Tree-shakable ESM. Only the categories you import end up in your bundle.

Versioning

• 0.x.y — schema may change between minor versions. Pin exactly.
• 1.0.0 — schema frozen. Patch = typo fixes. Minor = new items. Major = schema changes.

License

MIT. See LICENSE.