From Nepali Calendar Chaos to Code: Building NepaliCalendarToolkit

From Nepali Calendar Chaos to Code: Building NepaliCalendarToolkit

How being a solo developer for Nepali clients led me to create the NepaliCalendarToolkit NuGet package.

The Phone Call That Changed Everything

"Sushil Ji…" The client's voice was clear with their requirements. "We need separate reports for weekdays, weekends, and holidays."

"No problem," I replied confidently. After all, how hard could it be to filter out Saturday, Sunday, and Holidays?

A few days later, my confidence was shattered.

In Nepal, government offices follow a Saturday-only weekend system, while most private and corporate companies take both Saturday and Sunday off. And don't even get me started on the holidays…

The Holiday Nightmare

Nepali holidays aren't just fixed dates — they're a beautiful chaos of:

Traditional festivals following lunar calendars Government holidays announced last minute Regional variations (Kathmandu celebrates differently than Pokhara) Public holidays that fall on weekends — do they carry over?

I found myself manually creating holiday data, updating them each year, and constantly explaining to my team why our report showed "Maha Shivaratri" as a working day.

Spoiler: because my data was wrong.

Building NepaliCalendarToolkit

After a few painful days, I built NepaliCalendarToolkit.

dotnet add package NepaliCalendarToolkit

Holiday and Weekend Tracking

// Get everything for the year 2082
var holidaysAndWeekends = NepaliCalendarConverter.GetHolidaysAndWeekends(2082);
// Get just holidays for a specific month
var holidays = NepaliCalendarConverter.GetHolidaysAndWeekends(
    2082, 1, HolidayOrWeekendEnum.Holidays);
// Get just weekends for a specific month
var weekends = NepaliCalendarConverter.GetHolidaysAndWeekends(
    2082, 1, HolidayOrWeekendEnum.Weekends);

Date Conversion Made Simple

Convert between Nepali BS and Gregorian AD dates:

// Nepali (BS) → AD
var nepaliDate = new NepaliDate(2082, 1, 1);
var gregorianDate = NepaliCalendarConverter.ConvertToAD(nepaliDate);
// AD → Nepali (BS)
var date = new DateTime(2025, 4, 14);
var convertedNepaliDate = NepaliCalendarConverter.ConvertToNepali(date);

Fiscal Year Operations

Nepal's fiscal year runs from Shrawan 1 to Ashad end. The toolkit handles it natively:

// Full fiscal year date range in AD
var fiscalYearRange = NepaliCalendarConverter.GetFiscalYearDateRangeInAD(2082);
// → StartDate: 2025-07-17, EndDate: 2026-07-16
// All holidays within a fiscal year
// Monthly date range
var monthRange = NepaliCalendarConverter.GetStartAndEndDateInAD(2082, 6);
// → StartDate: 2025-10-18, EndDate: 2025-11-16
// Custom multi-month range (month 6 to month 8)
var customMonthRange = NepaliCalendarConverter.GetMonthRangeDateInAD(2082, 6, 8);
// → StartDate: 2025-10-18, EndDate: 2026-01-14

Holiday Data Structure

The toolkit stores holiday data in simple JSON files — one per year:

[
  {
    "month": 1,
    "day": 11,
    "date": "2025-04-24",
    "name": "Loktantra Diwas"
  }
]

Each year has its own 2082.json file, making updates and maintenance straightforward. No hardcoded arrays. No spaghetti lookup tables.

Want to contribute holidays for an upcoming year? Open a PR on GitHub with the new JSON file.

Real-World Use Cases

These are the actual scenarios that drove every feature in the toolkit:

Payroll Systems — calculate real working days for salary processing, excluding weekends and holidays specific to government or private sector rules.

Project Management — accurately plan project timelines that don't pretend Dashain week is just a regular sprint.

Attendance Systems — differentiate between actual absences and legitimate holidays or weekends, so your HR team stops getting angry emails.

Reporting Tools — generate accurate productivity reports for clients without manually patching holiday data every year.

The Problem It Solves in One Line

// Before: manually maintained, always out of date, always wrong on Maha Shivaratri
var isHoliday = myHardcodedList.Contains(today); // good luck
// After:
var isHoliday = NepaliCalendarConverter
    .GetHolidaysAndWeekends(2082)
    .Any(h => h.Date == today);

The package supports both Saturday-only weekends (government) and Saturday + Sunday weekends (private sector) via the HolidayOrWeekendEnum.

Get Started

dotnet add package NepaliCalendarToolkit