date-fns-jalali is a comprehensive JavaScript utility library that adapts the popular `date-fns` toolset for the Jalali (Persian) calendar system. It provides over 200 functions for manipulating, formatting, and comparing dates, all while adhering to `date-fns`'s principles of modularity, immutability, and native Date object usage. The library is currently at version `4.1.0-0` and maintains a release cadence closely tied to its upstream `date-fns` dependency, frequently rebasing to incorporate new features and fixes. Key differentiators include its pure function approach, full TypeScript support, and robust internationalization capabilities, making it a reliable choice for applications requiring Jalali calendar functionality in both browser and Node.js environments.
npm install date-fns-jalaliVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates basic date formatting from Gregorian to Jalali, creating a new Jalali date object, and sorting dates using `date-fns-jalali`'s core functions.
Review any existing logic that relies on `isWeekend` or `isBusinessDay` functions and adjust expectations or custom weekend definitions accordingly.
Always check the `date-fns` changelog for the corresponding version when upgrading `date-fns-jalali`. Thoroughly test date-related logic after any upgrade.
Consistently use `newDate(year, month, day)` for creating Jalali calendar dates and convert to/from Gregorian `Date` objects when interacting with other JavaScript APIs if necessary. The `format` function can still accept native `Date` objects for formatting.
Ensure you are using `import { format } from 'date-fns-jalali';` for ES Modules. If in a CommonJS environment, verify your build process handles ESM imports correctly or check if a specific CJS export is available (less common for this library).Double-check the arguments passed to `newDate` and other date manipulation functions, ensuring they are within the valid ranges for Jalali year, month, and day. Remember that Jalali months are typically 1-12, and days vary by month and leap year.
Import the required locale explicitly using `import faIR from 'date-fns-jalali/locale/fa-IR';` and pass it to functions that accept a `locale` option, e.g., `format(date, 'PPP', { locale: faIR })`.