한국 음력·만세력 변환 라이브러리 (kor-lunar-js · manseryeok-js)

kor-lunar-js는 한국 음력 변환 유틸리티이고, manseryeok-js는 만세력(萬歲曆)을 다루는 JavaScript 라이브러리입니다. kor-lunar-js는 2025년 4월 시작해 2026년 8월 기준 스타 54개, manseryeok-js는 2026년 1월 시작해 스타 41개·포크 17개를 기록 중입니다.

음력 변환이 왜 까다로운가

음력은 달의 주기를 따르므로 한 달이 29일 또는 30일이고, 윤달이 불규칙하게 들어갑니다. 규칙적인 계산식으로 딱 떨어지지 않아서, 정확하려면 천문 계산을 하거나 미리 계산된 역법 데이터를 참조해야 합니다. 대충 만들면 특정 연도에서 하루씩 어긋납니다.

만세력이란

만세력은 양력·음력·간지(갑자·을축…)·절기를 함께 담은 역법 표입니다. 사주·명리 계산의 기초 자료이고, 전통 의례 날짜 산정에도 쓰입니다. 단순 음력 변환보다 다루는 정보가 많습니다.

어디에 쓰이나

• 생일 앱: 음력 생일 알림 (한국에서는 여전히 흔함)
• 제사·명절 일정 관리
• 사주·운세 서비스
• 전통 문화 콘텐츠
• 캘린더 앱의 음력 표시

한국·중국·일본의 차이

음력은 동아시아 공통이지만 나라마다 기준 시각(경도)이 달라 하루 차이가 나는 경우가 있습니다. 그래서 중국 음력 라이브러리를 그대로 쓰면 한국 날짜와 어긋날 수 있고, 한국 기준으로 검증된 구현이 따로 필요합니다.

사주 앱의 문턱을 낮추는 기반

운세·사주 앱은 한국에서 꾸준히 수요가 있는 카테고리인데, 그 기반 계산을 직접 구현하려면 진입 장벽이 높습니다. 이런 라이브러리가 있으면 그 위에 서비스를 만드는 비용이 크게 낮아집니다. 기반 계층이 생기면 응용이 늘어납니다.

같은 결의 한국 특화 라이브러리

• Hangulize (외래어 한글 표기)
• go_hangul (한글 자모 처리)
• awesome-hangul (한글 라이브러리 큐레이션)
• 표준주소실록 gjdong (주소 정규화)

그리고 윤달 처리와 절기 계산은 구현마다 미세하게 다를 수 있습니다. 제사·생일처럼 틀리면 안 되는 용도라면 공식 만세력과 표본 대조를 해두는 편이 안전합니다.

이런 분께 맞아요

• 음력 생일·제사 알림 기능이 필요한 앱 개발자
• 사주·운세 서비스를 만드는 메이커
• 캘린더에 음력을 표시해야 하는 개발자
• 한국 전통 역법을 코드로 다루려는 사람