# chinese-days: a holiday, workday and lunar calendar dataset that updates itself

> chinese-days is a TypeScript library and data package for Chinese statutory holidays, make-up workdays, the 24 solar terms and lunar to Gregorian conversion, published to npm and also as JSON and iCal files so a non-JavaScript project can consume it and a calendar client can subscribe to it. A daily action reads the official announcement for the following year, generates a proposal and asks a human to review it.

**vsme/chinese-days** — 中国法定节假日、调休和工作日、24节气查询，农历阳历互转，提供 JSON 文件，对非开发者，还提供 iCal 日历订阅，可供 Google Calendar、Apple Calendar、Microsoft Outlook 等客户端使用。

- Repository: https://github.com/vsme/chinese-days
- Website: https://chinese-days.yaavi.me
- Stars: 1,313 · Forks: 58
- Language: TypeScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/vsme-chinese-days

## What the package actually contains

The package description in Chinese is the clearest statement of scope. It is a query tool for Chinese statutory holidays, make-up workdays, workdays, the 24 solar terms, and lunar to Gregorian conversion, supporting TypeScript, CommonJS and UMD modular usage, and providing the ics calendar format for subscription by Google Calendar, Apple Calendar, Microsoft Outlook and similar clients. The npm name is chinese-days, the version is 1.5.9, the licence is MIT, and the primary language is TypeScript. The topic is narrow and unglamorous, which is the point: a developer who needs to know whether a date is a working day in China is a real and common problem, and the answer is usually a maintained table of exceptions rather than an algorithm.

## The data ranges, and they are not the same for each dataset

The documentation lists the coverage for the three datasets separately, and the difference matters. The statutory holidays and make-up workdays are supported from 2004 to 2026, including the extended Spring Festival in 2020. The 24 solar terms are supported from 1900 to 2100. The lunar calendar dates are supported from 1900 to 2100. So a calendar calculation or a solar term query works over two centuries, while the holiday rules, which are the part that actually changes every year, are only good for a twenty three year window and end in 2026. That is a hard boundary for anyone planning a long-lived deployment, and it is the reason the automation section exists.

## The automation, and where a human still sits in the loop

The automation section is the part that distinguishes this from a static dataset, and it is worth reading closely because the division of labour is deliberate. An AI integration extracts the official announcement and judges the make-up workday dates, and a program validates the result and creates the pull request, with no manual filling in of the make-up work rules. Only the year after the largest already covered year is added, and existing years are skipped. If validation fails, the feedback goes back to the AI to retry, and an email is sent only when the pull request actually changed something. After an official holiday pull request is reviewed and merged, the patch version is incremented automatically, a tag is created and npm publish happens, while a test pull request does not trigger a release. So the data entry is automated, the validation is automated, and the merge is still a person.

## Using it from a language that is not JavaScript

The package makes a point of serving people who are not writing JavaScript or TypeScript. A JSON file of the Chinese holidays is published on a CDN and can be referenced directly, and if you need a JSON file per year there is one for each year from 2004 onwards, with the year files also published individually. The README gives a Java example pointing at a separate repository, Warnier-zhang/java-chinese-days, described as being for querying only the Chinese holidays, make-up workdays and workdays. The reasoning is sound. A calendar rule is a data problem, not a language problem, and publishing the table as JSON means nobody has to reimplement the lunar conversion to check a date.

## Calendar subscription, which is the feature most people will actually use

The calendar subscription section is the most immediately useful part of the package for a lot of people. You point Google Calendar, Apple Calendar or Microsoft Outlook at the subscription URL for the holidays file, and there is an English variant of the same feed for people who need the event titles in English. The subscribed calendar contains the last three years of holidays and make-up workdays, and there are per-year iCal files as well, again for 2004 and after, with English versions alongside. The practical difference between this and doing it by hand is that the subscription updates itself when the package publishes a new version, so a team that has subscribed once does not have to remember to re-import the calendar every December.

## The data format, and the contributors who chose it

The configuration format is described as keeping the .r(), .w() and .i() shapes, with the detailed process and the automatic validation rules in the contributing guide under the section on generating a new year automatically, and a reference pull request for the 2025 configuration. The contributor instructions are short. You fork and clone the project, then to change the holidays you edit the holiday definition file, to change the lunar calendar you edit the lunar definition file, then you submit a pull request. The acknowledgements are worth noting for provenance. The lunar data comes from the Bigkoo Android-PickerView project, the Chinese holiday data generation was modelled on the Python version of the LKI chinese-calendar project, and there is thanks to a well known Chinese developer for the recommendation. The primary language is TypeScript and the recent releases are v1.5.5 and v1.5.7 on the same day in March 2026 and v1.5.9 in June.

## The build, the tests and the scripts that do the work

The package manifest shows a TypeScript project with a conventional layout, with src/ for the library, scripts/ for the tooling, test/ for the Jest suite, and docs/ for the documentation, and a jest.config.ts and vite.config.ts at the top level along with a tsconfig.scripts.json for the script code. The build script runs the TypeScript compiler, then the Vite build, then a script to build the JSON and another to build the ics files, which is why the JSON and calendar outputs are generated artefacts of the same build as the library rather than something maintained by hand. The script entries are the interesting part, because they map onto the automation described in the README. There is a fetch script, an auto-update-holidays script, separate test scripts for the AI extraction and for the notification, a release:prepare script, and a check:scripts target that type checks the scripts separately from the library.

## Where the project stands, and the hosting question

The homepage is chinese-days.yaavi.me, which is the documentation site, and the README points there for the full documentation, and there is a separate English README in the repository. The last push was on 2026-10-11, the repository is not archived, and the default branch is main. Two things are worth noting for a team adopting it. The first is the hosting, since the CDN URLs for the JSON and ics files are the documented consumption path and they point at a published npm package, which means your calendar subscription depends on a package version rather than on a service you control. The second is the automation, since a daily action checks the next year's official announcement and generates a proposal, so the data stays current without anyone remembering, and an existing year is never touched once it has been added.

## Conclusion

chinese-days suits a developer building anything that has to know whether a given date is a Chinese public holiday, a make-up workday or an ordinary working day, and it is genuinely useful outside JavaScript because the JSON and iCal outputs are plain files. It is the wrong choice for a one-off lookup, since the CDN URL answers that without installing anything, and a poor fit if you need the rules to be legally authoritative, because the underlying data is a community project rather than a government source. Before you rely on it, check the year range you need, since the holiday data covers 2004 to 2026 while the solar terms and the lunar calendar run from 1900 to 2100, and read the contributing guide if you want to supply a year the automation has not yet produced.

## FAQ

### What does the chinese-days package provide?

Functions to query Chinese statutory holidays, make-up workdays, workdays and the 24 solar terms, plus lunar to Gregorian conversion, with TypeScript, CommonJS and UMD module support, published to npm as chinese-days under the MIT licence.

### How do I use Chinese holiday data without JavaScript?

The project publishes a JSON file of the Chinese holidays on a CDN that can be referenced directly, and also per-year JSON files for 2004 and after. For Java there is a separate repository, Warnier-zhang/java-chinese-days, covering only the holidays, make-up workdays and workdays queries.

### Can I subscribe to Chinese holidays in Google Calendar or Outlook?

Yes, by pointing the client at the published holidays.ics subscription URL, with an English variant at holidays.en.ics. The subscribed calendar contains the last three years of holidays and make-up workdays, and per-year iCal files are published too for 2004 and after.

### How does the Chinese holiday data stay up to date?

A daily action checks the official announcement for the following year, extracts it with an AI integration that also judges the make-up workday dates, validates the result and creates a pull request. Only the year after the largest already covered year is added, validation failure is fed back for retry, and an email is sent only when the pull request actually changed something.

### What date ranges does chinese-days cover?

The statutory holidays and make-up workdays are supported from 2004 to 2026, including the extended 2020 Spring Festival. The 24 solar terms and the lunar calendar dates are both supported from 1900 to 2100. The package version is 1.5.9 and the licence is MIT.

## Sources

- [License: MIT](https://github.com/vsme/chinese-days/blob/main/LICENSE)
- [Project website](https://chinese-days.yaavi.me)
- [README](https://github.com/vsme/chinese-days/blob/main/README.md)
- [Releases](https://github.com/vsme/chinese-days/releases)
- [vsme/chinese-days on GitHub](https://github.com/vsme/chinese-days)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vsme-chinese-days