Chinese Days

This project provides a series of functions for querying Chinese holidays, adjusted working days, working days, 24 solar terms, and converting between lunar and solar calendars. Provide JSON file, Additionally, it supports ics file subscription for holidays, which can be subscribed to by Google Calendar, Apple Calendar, Microsoft Outlook, and other clients.

Automation

Automation only appends the year after the latest recorded year; existing years are skipped. AI extracts official notice facts and proposes in-lieu dates with explanations. Statutory dates, compensatory rest and calendar conflicts are validated automatically, with correction retries before creating a regular PR. No per-year manual rules or in-lieu confirmation step is required. Email is sent only when the PR changes. The existing .r(), .w(), and .i() format is preserved. Merging a production holiday PR into main automatically increments the patch version, creates a version tag and publishes to npm. Test PRs do not trigger a release.

Documentation

To check out docs, visit chinese-days.yaavi.me.

The holiday information will be updated according to the announcements from the State Council.

• Holidays: Supports the years 2004 to 2026, including the extended Spring Festival of 2020.
• 24 Solar Terms: Supports the years 1900 to 2100.
• Lunar Days: Supports the years 1900 to 2100.

Subscribe to Calendar

The subscribed calendar includes holidays and adjusted working days for the past three years (2024-2026).

Subscription URL: https://cdn.jsdelivr.net/npm/chinese-days/dist/holidays.ics (default language is Chinese)

For English: https://cdn.jsdelivr.net/npm/chinese-days/dist/holidays.en.ics

If you need a ics file for a specific year, you can also reference it through this link: https://cdn.jsdelivr.net/npm/chinese-days/dist/years/2025.en.ics, and the Chinese version is https://cdn.jsdelivr.net/npm/chinese-days/dist/years/2025.ics.

For non-JS projects, you can use the JSON file

A JSON file of Chinese holidays is provided and can be directly referenced through this link: chinese-days.json.

If you need a JSON file for a specific year, you can also reference it through this link: years/2025.json.

For example, in Java, you can refer to Warnier-zhang/java-chinese-days, which is only for querying Chinese holidays, in-lieu days, and regular workdays.

Contributing

1. Fork + Clone the project to your local machine;
2. Holidays: Modify the holiday definitions;
3. Lunar definitions: Modify the lunar definitions;
4. For other modifications, refer to the source code yourself;
5. Submit a PR.

Acknowledgements

1. Lunar calendar data is sourced from the Bigkoo/Android-PickerView project.
2. Chinese holiday data generation references the Python version of the LKI/chinese-calendar project.
3. Thank you for the recommendation from Mr. Ruan Yifeng.