hindu-devotional-texts

Typed, hand-curated Hindu devotional text — aartis, chalisas, kathas, and full scriptures — 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 and versioned in git, intended to be the authoritative reference itself — consumers don't need to cross-check anywhere else.

Status: early development (0.0.x). The schema and getter API are stable; content is being filled in progressively. 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).

Quick start

import {
  getAarti,
  getChalisa,
  getKatha,
  getScripture,
  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 geeta = getScripture('bhagavad-geeta')
// { slug, titleEnglish, titleHindi, chapters, about }

const everythingForShiva = getContentForDeity('shiva')
// { aarti?, chalisa?, kathas: Katha[] }

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

import type {
  Recitation, Chalisa, Katha, Scripture,
  Deity, KathaSlug, ScriptureSlug,
} 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 (Shiva → Shiv Mahapuran + Solah Somvar), 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 also a string literal union with IDE autocomplete.

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

Aggregate

getContentForDeity(deity: Deity): {
  aarti?: Recitation
  chalisa?: Chalisa
  kathas: Katha[]
}

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 Chalisa {
  slug: string
  deity: Deity
  titleEnglish: string
  titleHindi: string
  openingDoha?: { english; hindi }   // couplets at the start
  soratha?:     { english; hindi }   // inverted-meter couplet (e.g. Lakshmi)
  chaupai:      { english; hindi }   // the 40-ish main verses
  closingDoha?: { english; hindi }
  about: { en: string; hi: string }
}

interface Katha {
  slug: string
  deity?: Deity
  titleEnglish: string
  titleHindi: string
  about: { en: string; hi: string }
  samagri: { intro?: KathaParagraph; items: SamagriItem[] }
  vidhi:    KathaParagraph[]
  chapters: KathaChapter[]          // each with { number, titleEnglish, titleHindi?, paragraphs, sampurna }
}

interface KathaParagraph {          // at least one field required
  english?: string                  // prose English
  hindi?: string                    // prose Hindi (Devanagari)
  sanskrit?: string                 // embedded shloka (Devanagari)
  iast?: string                     // Roman transliteration of `sanskrit`
}

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 translation
}

Source of truth: src/types.ts.

What's currently populated

| Category | Scope | Populated | |---|---|---| | aartis | 19 deities | all 19 | | chalisas | 19 deities | all 19 | | kathas | 10 (satyanarayan, shrimad-bhagwat, shiv-mahapuran, ram, devi-bhagwat, vaibhav-lakshmi, santoshi-mata, karva-chauth, solah-somvar, ahoi-ashtami) | satyanarayan only (rest in progress) | | scriptures | bhagavad-geeta (18 ch, ~700 verses), sundarkand (68 sargas) | scaffolded (content in progress) |

Aarti/chalisa getters take a Deity and return Recitation | undefined / Chalisa | undefined — check for undefined before rendering. Katha/scripture getters take a slug union whose values are guaranteed to exist in the registry, so they return non-nullable Katha / Scripture.

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) — some are chaupai-only (Durga), some add opening/closing dohas (Ganesha), some also have a soratha (Lakshmi). Render each section only if present.
• Kathas render as: samagri.intro (if present) → samagri.items as a list → vidhi paragraphs → each chapter (title + paragraphs + sampurna closing line). 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 per verse. Bhagavad Geeta will carry all three; Sundarkand will likely be Devanagari-only.
• Titles are always bilingual (titleEnglish + titleHindi) — route on titleEnglish/slug, surface titleHindi in UI.
• Dates / panchang (when to observe a vrat, tithi calculations) are out of scope.

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 — the optional fields on KathaParagraph let a paragraph be whatever it naturally is.
• Scriptures use full IAST diacritics in iast fields. No ITRANS, no Harvard-Kyoto, no ad-hoc schemes.

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-generated content. Every item is hand-verified against canonical traditional text before it ships.
• 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.