Bringing History to the Modern Web: Introducing moment-shahanshahi for JavaScript & React 👑

Vahid Afshari — Sat, 21 Mar 2026 08:18:22 +0000

As developers, we often deal with timezones and calendars. While the Gregorian calendar is the global standard, many cultures use their own traditional systems. In the Iranian context, while the Solar Hijri (Jalaali) calendar is widely used, there is also the Iranian Imperial (Shahanshahi) Calendar system dating back to the founding of the Achaemenid Empire by Cyrus the Great.
Today, I’m excited to introduce moment-shahanshahi, a lightweight npm package that makes it incredibly easy to integrate the Shahanshahi calendar into your JavaScript and React applications.

Why a new package?

While there are excellent libraries like moment-jalaali for Persian dates, converting those dates to the Imperial era (which starts 1,180 years before the Hijri era) usually requires manual calculations and custom formatting logic.
I built moment-shahanshahi to bridge this gap, providing a seamless wrapper around the reliable moment core while adding specific support for the Imperial era.
Key Features
✅ Familiar Syntax: Built on top of moment-jalaali, so if you know Moment.js, you already know how to use this.
✅ Custom Tokens: Introducing sYYYY and sYY tokens specifically for Shahanshahi years.
✅ React Ready: Comes with a built-in React component (ShahanshahiDate) for quick UI implementation.
✅ Precision: Uses the same astronomical calculations as the Jalaali calendar, ensuring perfect accuracy.
Getting Started
You can install it via npm or yarn:

npm install moment-shahanshahi moment
1. Using it in Vanilla JavaScript
You can format any date into the Shahanshahi era using the .sFormat() method:

const moment = require('moment-shahanshahi');

// Current date in Shahanshahi format (e.g., 2583/01/01)
console.log(moment().sFormat('sYYYY/jMM/jDD'));

// Converting a historical date
const date = moment('1971-10-12');
console.log(date.sFormat('sYYYY [Year of the] jMMMM')); 
// Output: 2530 Year of the Mehr

2. Using it in React
For React developers, I've included a handy component to keep your JSX clean:

import { ShahanshahiDate } from 'moment-shahanshahi';

function App() {
  return (
    <div>
      <h1>Current Era:</h1>
      <ShahanshahiDate 
        date={new Date()} 
        format="sYYYY/jMM/jDD" 
        className="imperial-text" 
      />
    </div>
  );
}

The Logic Behind the Calendar

The Shahanshahi calendar is mathematically identical to the Solar Hijri (Jalaali) calendar in terms of leap years and month lengths. The only difference is the epoch (starting point).
The conversion logic is simple yet effective:
Shahanshahi Year = Jalaali Year + 1180
By leveraging moment-jalaali, this package ensures that all month names, days, and leap-year calculations remain 100% accurate while simply shifting the year to the Imperial era.
Open Source & Contributions
This project is open-source and I would love to hear your feedback! Whether it's adding support for other date libraries (like Day.js) or improving the React hooks, contributions are always welcome.

NPM: moment-shahanshahi
GitHub:GitHub Repo

If you find this useful, feel free to give it a ⭐️ on GitHub and share it with other developers working on Persian-localized application

DEV Community: Vahid Afshari

Bringing History to the Modern Web: Introducing moment-shahanshahi for JavaScript & React 👑