{"id":10718,"library":"date-fns-jalali","title":"date-fns-jalali","description":"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.","status":"active","version":"4.1.0-0","language":"javascript","source_language":"en","source_url":"https://github.com/date-fns-jalali/date-fns-jalali","tags":["javascript","typescript"],"install":[{"cmd":"npm install date-fns-jalali","lang":"bash","label":"npm"},{"cmd":"yarn add date-fns-jalali","lang":"bash","label":"yarn"},{"cmd":"pnpm add date-fns-jalali","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This library is a wrapper/extension of date-fns, providing its functionalities adapted for the Jalali calendar. It frequently rebases to align with date-fns versions.","package":"date-fns","optional":false}],"imports":[{"note":"date-fns-jalali is primarily designed for ESM usage. CommonJS `require` might lead to issues depending on your build configuration.","wrong":"const format = require('date-fns-jalali').format;","symbol":"format","correct":"import { format } from 'date-fns-jalali';"},{"note":"`newDate` is the library's factory function for creating Jalali calendar dates, analogous to `new Date()` for Gregorian dates. Individual functions are not typically default exports from subpaths.","wrong":"import newDate from 'date-fns-jalali/newDate';","symbol":"newDate","correct":"import { newDate } from 'date-fns-jalali';"},{"note":"Locales are usually imported as default exports from specific subpaths to enable tree-shaking and only include necessary translations.","wrong":"import { faIR } from 'date-fns-jalali';","symbol":"faIR locale","correct":"import faIR from 'date-fns-jalali/locale/fa-IR';"}],"quickstart":{"code":"import { compareAsc, format, newDate } from \"date-fns-jalali\";\n\n// Format a Gregorian Date to Jalali string\nconst gregorianDate = new Date(2014, 1, 11); // February 11, 2014\nconsole.log(`Gregorian date (${gregorianDate.toLocaleDateString()}) formatted to Jalali: ${format(gregorianDate, \"yyyy-MM-dd\")}`);\n// Expected output: '1392-11-22'\n\n// Create a new Jalali Date object\nconst jalaliDate = newDate(1392, 10, 22); // Jalali 1392 Bahman 22\nconsole.log(`New Jalali date (1392/10/22): ${jalaliDate.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric'})}`);\n// Expected output: a Date object representing Tue Feb 11 2014 00:00:00\n\n// Format the Jalali Date object with a specific Jalali format (assuming locale is applied or inferred)\nconsole.log(`Formatted Jalali date: ${format(jalaliDate, \"yyyy MMMM d\")}`);\n// Expected output: '1392 بهمن 22'\n\n// Sort an array of Gregorian dates using date-fns-jalali's compare function\nconst dates = [\n  new Date(1995, 6, 2),\n  new Date(1987, 1, 11),\n  new Date(1989, 6, 10),\n];\ndates.sort(compareAsc);\nconsole.log('Sorted dates:', dates.map(d => d.toLocaleDateString()));\n// Expected output: [Feb 11 1987, Jul 10 1989, Jul 02 1995]\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Review any existing logic that relies on `isWeekend` or `isBusinessDay` functions and adjust expectations or custom weekend definitions accordingly.","message":"In version `4.0.0-0`, the logic for weekend and business days was changed. Only Friday is now considered a weekend day, which may affect calculations involving business days or weekend checks.","severity":"breaking","affected_versions":">=4.0.0-0"},{"fix":"Always check the `date-fns` changelog for the corresponding version when upgrading `date-fns-jalali`. Thoroughly test date-related logic after any upgrade.","message":"date-fns-jalali frequently rebases to the upstream date-fns library. This means that breaking changes, new features, or behavior shifts introduced in major or minor versions of `date-fns` will propagate to `date-fns-jalali`. Users should consult `date-fns` release notes in addition to `date-fns-jalali`'s.","severity":"gotcha","affected_versions":">=3.0.0-0"},{"fix":"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.","message":"When working with Jalali dates, use `newDate` provided by `date-fns-jalali` instead of the native `new Date()` constructor. Mixing them can lead to unexpected behavior or incorrect calendar calculations.","severity":"gotcha","affected_versions":">=2.0.0-0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"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).","cause":"Attempting to use CommonJS `require()` syntax or incorrect named import when the library primarily supports ES Modules, or a bundler issue.","error":"TypeError: format is not a function"},{"fix":"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.","cause":"This error often occurs when date functions receive arguments that do not represent valid date components (e.g., incorrect month or day numbers for the Jalali calendar, or an invalid type passed to `newDate`).","error":"RangeError: Invalid time value"},{"fix":"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 })`.","cause":"A locale object (like `faIR` for Farsi/Persian) was used in a formatting function but was not correctly imported or provided to the function's options.","error":"ReferenceError: faIR is not defined"}],"ecosystem":"npm"}