Skip to content
Tết −50%Đoàn Viên, only 99,500 VND first yearĐoàn Viên, first year only 99,500 VND, 1 personal reading a yearSee the offer

Blog

Add the lunar calendar, festivals and death anniversaries to your app in TypeScript or Python

February 2027 with lunar dates, festivals and the code that built it

A lunar calendar, death anniversaries and festivals for your app or website take two packages: @nhatnguyet/am-lich and @nhatnguyet/le-hoi (the Python package is nhatnguyet). Dates are computed in Vietnam time, with new moons checked against NASA and the 24 solar terms against IMCCE from 1900 to 2100; festivals come from the open dataset of 206 Vietnamese festivals in three languages.

Steps

  1. Install the packages (TypeScript or Python).
  2. Convert a solar date to lunar: solarToLunar(ngay, thang, nam).
  3. Compute a death anniversary: take the lunar date of death, then call lunarToSolar(ngayAm, thangAm, nam, false) for each year.
  4. List the year's festivals with leHoiTrongNam(nam), or the festivals on one day with leHoiTheoNgay(ngay, thang, nam).
  5. For the Chinese or Korean calendar, pass a time zone from MUI_GIO_LICH.
npm i @nhatnguyet/am-lich @nhatnguyet/le-hoi
pip install nhatnguyet

TypeScript code and output

import { solarToLunar, lunarToSolar, yearCanChi, MUI_GIO_LICH } from "@nhatnguyet/am-lich";
import { leHoiTrongNam, leHoiTheoNgay, DANH_SACH_LE_HOI } from "@nhatnguyet/le-hoi";

// Step 2: the lunar date of a solar date
const am = solarToLunar(19, 11, 2026);
console.log(`19/11/2026 is lunar ${am.day}/${am.month}, year ${yearCanChi(am.year).label}`);

// Step 3: a death anniversary by the lunar date of death
const mat = solarToLunar(12, 4, 2019);
console.log(`Died 12/4/2019, lunar ${mat.day}/${mat.month}`);
for (const nam of [2027, 2028, 2029]) {
  const { duong } = lunarToSolar(mat.day, mat.month, nam, false);
  console.log(`Anniversary ${nam}: ${duong.day}/${duong.month}/${duong.year}`);
}

// Step 4: the year's festivals, sorted by date
const name = Object.fromEntries(DANH_SACH_LE_HOI.map((l) => [l.id, l.ten_en]));
const fest = leHoiTrongNam(2027).sort((a, b) => a.ngay.localeCompare(b.ngay));
console.log(`2027 has ${fest.length} fixed-date festivals, the first four:`);
for (const l of fest.slice(0, 4)) console.log(" ", l.ngay, name[l.id]);
console.log("6/2/2027:", leHoiTheoNgay(6, 2, 2027).map((l) => l.ten_en).join(", "));

// Step 5: lunar new year by the Vietnamese, Chinese and Korean calendars
for (const nuoc of ["vietNam", "trungQuoc", "hanQuoc"]) {
  const t = lunarToSolar(1, 1, 1985, false, MUI_GIO_LICH[nuoc]).duong;
  console.log(`New Year 1985, ${nuoc} calendar: ${t.day}/${t.month}/${t.year}`);
}
19/11/2026 is lunar 11/10, year Bính Ngọ
Died 12/4/2019, lunar 8/3
Anniversary 2027: 14/4/2027
Anniversary 2028: 2/4/2028
Anniversary 2029: 21/4/2029
2027 has 164 fixed-date festivals, the first four:
  2027-01-01 New Year's Day
  2027-02-03 Founding Anniversary of the Communist Party of Vietnam
  2027-02-06 Lunar New Year (Tết)
  2027-02-09 Chùa Keo Spring Festival
6/2/2027: Lunar New Year (Tết)
New Year 1985, vietNam calendar: 21/1/1985
New Year 1985, trungQuoc calendar: 20/2/1985
New Year 1985, hanQuoc calendar: 20/2/1985
Lunar calendar, anniversary and festival code in TypeScript with its output
Lunar calendar, anniversary and festival code in TypeScript with its output

Someone who died on 12 April 2019 died on the 8th day of the 3rd lunar month, so the anniversary falls on 14/4/2027, 2/4/2028 and 21/4/2029. In 2027, 164 festivals have a computable date; the rest are announced each year by their organisers, see the lich_cong_bo column.

The same in Python

Function names match the TypeScript ones in snake_case; results are dicts with the same keys.

from nhatnguyet import am_lich, le_hoi

am = am_lich.solar_to_lunar(19, 11, 2026)
print(f"19/11/2026 is lunar {am['day']}/{am['month']}, year {am_lich.year_can_chi(am['year'])['label']}")

mat = am_lich.solar_to_lunar(12, 4, 2019)
for nam in (2027, 2028, 2029):
    duong, _ = am_lich.lunar_to_solar(mat["day"], mat["month"], nam, False)
    print(f"Anniversary {nam}: {duong['day']}/{duong['month']}/{duong['year']}")

ten = {l["id"]: l["ten_en"] for l in le_hoi.danh_sach_le_hoi()}
for l in sorted(le_hoi.le_hoi_trong_nam(2027), key=lambda l: l["ngay"])[:2]:
    print(l["ngay"], ten[l["id"]])

for nuoc, mui in am_lich.MUI_GIO_LICH.items():
    tet, _ = am_lich.lunar_to_solar(1, 1, 1985, False, mui)
    print(f"New Year 1985, {nuoc}: {tet['day']}/{tet['month']}/{tet['year']}")
19/11/2026 is lunar 11/10, year Bính Ngọ
Anniversary 2027: 14/4/2027
Anniversary 2028: 2/4/2028
Anniversary 2029: 21/4/2029
2027-01-01 New Year's Day
2027-02-03 Founding Anniversary of the Communist Party of Vietnam
New Year 1985, viet_nam: 21/1/1985
New Year 1985, trung_quoc: 20/2/1985
New Year 1985, han_quoc: 20/2/1985
New Year 1985, nhat_ban: 20/2/1985
Lunar calendar code in Python with its output
Lunar calendar code in Python with its output

A month view with lunar dates and festivals

Loop over the days of the month, call solarToLunar for the small number in each cell and leHoiTheoNgay to highlight festival days. The picture below is February 2027 built that way: the Lunar New Year falls on Saturday 6 February.

February 2027 with lunar dates and festivals
February 2027 with lunar dates and festivals

Export an .ics calendar

festivalsIcs(2027) from @nhatnguyet/le-hoi (Python: festivals_ics(2027) in nhatnguyet.en) returns an iCalendar (RFC 5545) file with one all-day event per festival and the venue when known; import it into Google Calendar, Apple Calendar or Outlook. From the command line: npx @nhatnguyet/cli festivals 2027 --ics > festivals-2027.ics.

Things to know

  • Someone who died in a leap month: by common custom many families hold the anniversary in the regular month of the same number; passing false follows that custom.
  • The 30th of a short month: when a lunar month has only 29 days, lunarToSolar returns the 1st of the next month. To know whether the month is long or short, convert back with solarToLunar and compare.
  • Lunar festivals go in the regular month, never the leap month; in a year without that date the festival is missing from the list.
  • The Chinese and Korean calendars follow the same rules with a different local time. In 1985 the Vietnamese New Year fell on 21 January, the Chinese and Korean one on 20 February.

Credit

The code is MIT licensed. The festival dataset is CC BY 4.0: credit "Data: Nhat Nguyet (nhatnguyet.org)" when you republish it. The code repository is on the open source page, the dataset on the open data page.

Open dataLunar calendar, sexagenary and festival datasets under CC BY 4.0.Try itVietnamese festival calendarHolidays and festivals all year, where they happen, with maps.Try it

More from the blog

All blog posts