Getting Started

Install

npm install panchang-ts
# or: pnpm add panchang-ts / yarn add panchang-ts

The package ships ESM and CJS builds with full TypeScript types, has zero runtime dependencies, and targets ES2020. It runs in Node.js, modern browsers, and React Native (Hermes) — see Errors & Compatibility.

Quick start

import { getDailyPanchang } from 'panchang-ts';

const result = getDailyPanchang(
  new Date(2025, 0, 14),                      // January 14, 2025
  { latitude: 23.1765, longitude: 75.7885 },  // Ujjain, India
  { timezone: 330 },                          // IST = UTC+5:30 = 330 minutes
);
// → DailyPanchangResult | null. Null only at polar latitudes where
//   sunrise can't be computed. Anywhere else, narrow with `if (!result) return;`.

console.log(result!.angas.tithis[0].name);          // "Krishna Chaturdashi"
console.log(result!.angas.nakshatras[0].name);      // "Mrigashira"
console.log(result!.angas.vara.name);               // "Mangalawara"
console.log(result!.calendar.chandramasa.name);     // "Magha"
console.log(result!.calendar.samvat.vikramSamvat);  // 2081

The three arguments are the calendar date, a { latitude, longitude, elevation? } location, and an options object whose only required field is timezone — minutes from UTC (330 for IST) or an IANA zone name like 'Asia/Kolkata'. Every other option has a sensible default; the full list is in Options & Localization.

Reading output times

Every Date in a result is a real instant — .getTime() is the correct epoch millisecond. Every instant has a *Local companion: an offset-carrying ISO 8601 string, which is what you want for display.

result!.sun.rise;         // Date — 2025-01-14T01:39:44.172Z (the actual moment)
result!.sun.riseLocal;    // "2025-01-14T07:09:44.172+05:30"
result!.inauspicious.rahuKalam.start;       // Date
result!.inauspicious.rahuKalam.startLocal;  // string

// Just the wall clock:
result!.sun.riseLocal.slice(11, 16);   // "07:09"

// Anything else works too, because the Date is genuinely correct:
new Intl.DateTimeFormat('en-IN', { timeZone: 'Asia/Kolkata', timeStyle: 'short' })
  .format(result!.sun.rise);           // "7:09 am"

For an instant you derive yourself, formatInZone renders it the same way:

import { formatInZone } from 'panchang-ts';

const noon = new Date((result!.sun.rise.getTime() + result!.sun.set.getTime()) / 2);
formatInZone(noon, result!.timezone.offsetMinutes);  // "2025-01-14T12:27:31.086+05:30"

moon.rise / moon.set can be null — the Moon occasionally does not rise or set on a given calendar day, which is normal. moon.riseLocal / moon.setLocal are null exactly when they are.

The result is grouped

DailyPanchangResult has seven groups plus a handful of top-level fields. The groups are what tell you where to look:

Top level: date, location, timezone, ayanamsa, specialYogas, anandadiYoga, festivals, eclipse, chandraBalam, tarabala.

getDailyPanchang vs getInstantPanchang

getInstantPanchang uses the same group names for the subset an instant can answer: sun, moon, angas, calendar, inauspicious. There is no muhurtas or periods group, because those are properties of a Hindu day. Its results also carry no *Local fields — that call takes no timezone, so there is no zone to render a wall clock in.

When things go wrong

• Invalid inputs throw a typed PanchangError with a stable code — see Errors & Compatibility.
• At polar latitudes, getDailyPanchang / getInstantPanchang return null rather than throwing — the Hindu day is undefined when sunrise cannot be computed.
• On React Native with an older Hermes, pass timezone as a number — IANA strings need Intl. See Performance for the two-pass rendering pattern.