한국 음력 변환 유틸 / Korean lunar calendar converter
npm install kor-lunar이 라이브러리는 학습용으로 제작되었으며, 한국천문연구원(KASI)의 음력·양력 변환 데이터를 기반으로 한 자바스크립트 라이브러리입니다.
네트워크 요청 없이 오프라인에서도 동작하고, 별도의 외부 의존성이 없습니다.
> ⚠️ 주의: 데이터는 2025년 5월 20일 기준으로 갱신되었습니다.
> 이후의 중요한 변경 사항이 반영되지 않을 수 있으므로,
> 중요한 작업에는 아래 한국천문연구원 공식 API를 사용하시기 바랍니다.
- 음력 ↔ 양력 변환 - toLunar, toSolar
- 윤달 처리 - isLeapMonth 옵션
- 음력 간지 출력 - 세차(secha), 월건(wolgeon), 일진(iljin)
- 윤달인 경우 wolgeon은 빈 문자열로 반환됩니다
- TypeScript 지원 - 타입 정의 기본 제공
- Zero Dependencies - 외부 의존성 없음
- CJS / ESM / UMD — 다양한 환경에서 사용 가능
- 예제 사이트
- toLunar: 양력 → 음력 날짜 범위 1890년 1월 21일 ~ 2050년 12월 31일
- toSolar: 음력 → 양력 날짜 범위 1890년 1월 1일 ~ 2050년 11월 18일
_범위를 벗어난 날짜가 입력될 경우 RangeError가 발생하며, 오류 메시지에 입력한 날짜 정보가 포함됩니다._
``bash`
npm install kor-lunar
`html`
CDN 사용 시 전역 변수 korLunar로 접근할 수 있습니다.
`js`
import korLunar from "kor-lunar";
// 또는
const korLunar = require("kor-lunar");
Named export도 지원합니다:
`js`
import { toLunar, toSolar } from "kor-lunar";
`js
import korLunar from "kor-lunar";
// 양력 → 음력
console.log(korLunar.toLunar(2025, 6, 25));
// {
// year: 2025,
// month: 6,
// day: 1,
// isLeapMonth: false,
// secha: '을사',
// wolgeon: '계미',
// iljin: '을축',
// julianDay: 2460852,
// dayOfWeek: 3
// }
// 양력 → 음력 (윤달)
console.log(korLunar.toLunar(2025, 7, 25));
// {
// year: 2025,
// month: 6,
// day: 1,
// isLeapMonth: true,
// secha: '을사',
// wolgeon: '', // 윤달인 경우 월건은 빈 문자열
// iljin: '을미',
// julianDay: 2460882,
// dayOfWeek: 5
// }
// 음력 → 양력
console.log(korLunar.toSolar(2025, 6, 1, false));
// { year: 2025, month: 6, day: 25 }
console.log(korLunar.toSolar(2025, 6, 1, true));
// { year: 2025, month: 7, day: 25 }
`
> 권장되진 않지만, korLunar.LunarTable과 korLunar.SolarTable` 같은 내부 함수에 직접 접근할 수도 있습니다.
> 이를 통해 단순 음력 변환 뿐만 아니라, 더 다양한 기능을 구현할 수 있습니다.
> 예제 사이트: 음력 달력
- 한국천문연구원: https://www.kasi.re.kr
- 공공데이터포털: https://www.data.go.kr/data/15012679/openapi.do