한글 공문서(HWP/HWPX/PDF/스캔본)에서 본문 텍스트를 추출하는 Node.js/TypeScript 라이브러리.
English summary: A Node.js/TypeScript library for extracting plain text from Korean government/administrative documents in HWP, HWPX, PDF, and scanned-image form. HWP is the mandatory file format for Korean public institutions, yet open-source parsers for it are rare — this library fills that gap with a dependency-light, self-contained extraction pipeline (HWPX native XML parsing, HWP→HWPX conversion via an optional sidecar, parallel PDF text-layer extraction, and a Korean-OCR fallback chain). See "Installation" and "Usage" below for a minimal example; the rest of this README is in Korean.
HWP는 대한민국 정부·공공기관·지자체가 여전히 표준으로 사용하는 문서 포맷이다. 관공서 공고문, 입찰 공고, 행정 서식 등 상당수가 HWP/HWPX로 배포되는데, 이 포맷을 다루는 오픈소스 파서는 많지 않다(대부분 상용 SDK이거나 한/글 프로그램 설치를 전제로 한다). 이 라이브러리는
- 순수 JS로 HWPX(OWPML zip/XML)를 직접 파싱하고,
- 구 바이너리 포맷인 HWP는 별도 변환 사이드카(Java 기반
hwp2hwpx)를 거쳐 같은 파서로 처리하며, - 텍스트 레이어가 없는 PDF나 스캔본은 한글에 특화된 OCR 체인으로 폴백한다.
네트워크나 상용 API 없이도(HWPX/PDF 텍스트 레이어만으로) 핵심 기능이 동작하도록 설계했다.
npm install hwp-parserNode.js 20 이상이 필요하다.
메타데이터 없이 본문 텍스트만 필요할 때:
import { parseDocumentText } from "hwp-parser";
import { readFile } from "node:fs/promises";
const buffer = await readFile("공고문.hwp");
const text = await parseDocumentText(buffer, "공고문.hwp", "application/x-hwp");
console.log(text.slice(0, 200));추출 방식(method), 경고, 페이지 수 등 메타데이터까지 필요할 때:
import { extractDocument } from "hwp-parser";
const result = await extractDocument(buffer, "공고문.pdf", "application/pdf");
// result: { text, method, charCount, pageCount?, warning?, warnings?, conversionStatus?, elapsedMs? }HWPX만 직접 파싱하거나 HWP→HWPX 변환만 따로 쓰고 싶을 때:
import { extractHwpxPlainText, convertHwpToHwpx, detectHwpFormat } from "hwp-parser";
const format = detectHwpFormat("공고문.hwp", buffer); // "hwp" | "hwpx" | null
const text = await extractHwpxPlainText(hwpxBuffer);| 포맷 | 처리 방식 | 추가 설정 필요 여부 |
|---|---|---|
| HWPX | OWPML(Contents/section*.xml) 직접 파싱 |
불필요 |
| HWP | HWP→HWPX 변환 사이드카를 거쳐 위와 동일하게 처리 | HWP_CONVERTER_SERVICE_URL 설정 필요 |
| PDF(텍스트 레이어 있음) | pdfjs-dist 기반 병렬 텍스트 추출 |
불필요 |
| PDF(스캔본)·이미지 | OCR 체인 폴백(PaddleOCR → Vision → CLOVA → Gemini) | OCR 제공자 중 최소 1개 설정 필요 |
평문(.txt/.md/.csv/.json/.log/.xml) |
그대로 정규화 후 반환 | 불필요 |
OCR 제공자를 하나도 설정하지 않으면 스캔본/이미지 처리 시 에러를 반환한다(캡차 전용 OCR 엔진은 문서 인식에 부적합하므로 의도적으로 포함하지 않았다).
.hwp(구 바이너리 포맷)는 JS만으로 파싱할 수 없다. 이 리포에 포함된
services/hwp-converter/server.py가 Java 기반 hwp2hwpx를 호출하는 최소 HTTP 사이드카를
제공한다.
요구사항: Java 11 이상, Python 3.
cd services/hwp-converter
pip install -r requirements.txt
python server.py # 기본 포트 8790그 다음 라이브러리를 쓰는 쪽에서 환경변수로 주소를 지정한다.
HWP_CONVERTER_SERVICE_URL=http://127.0.0.1:8790.hwp 파일을 다루지 않는다면(HWPX/PDF/이미지만 처리) 이 사이드카 없이도 나머지 파이프라인은
정상 동작한다.
모두 선택값이다. .env.example 참고.
| 변수 | 설명 | 기본값 |
|---|---|---|
HWP_CONVERTER_SERVICE_URL |
HWP→HWPX 변환 사이드카 주소 | (하드코딩 기본값 없음 — 미설정 시 .hwp 처리가 명확한 에러로 실패) |
HWP_PARSER_OCR_SERVICE_URL |
로컬/자체 호스팅 PaddleOCR 사이드카 주소 | http://127.0.0.1:8791 |
HWP_PARSER_OCR_TIMEOUT_MS |
PaddleOCR 요청 타임아웃(ms) | 600000 |
HWP_PARSER_OCR_GEMINI_MODEL |
Gemini Vision OCR 모델명 | gemini-2.0-flash |
HWP_PARSER_PDF_PAGE_CONCURRENCY |
PDF 페이지 텍스트 추출 병렬도(2~8) | 4 |
GOOGLE_VISION_API_KEY |
Google Cloud Vision OCR API 키 | - |
CLOVA_OCR_URL, CLOVA_OCR_SECRET |
네이버 CLOVA OCR 엔드포인트/시크릿 | - |
GEMINI_API_KEY(또는 GOOGLE_GEMINI_API_KEY, GOOGLE_AI_API_KEY) |
Gemini Vision OCR API 키 | - |
npm install
npm run build # tsc -> dist/
npm test # node:test 기반 유닛 테스트 (네트워크/실제 HWP 파일 불필요)이 파서는 원래 다음 서비스의 문서 수급 파이프라인에서 쓰이던 모듈을 독립 라이브러리로 분리한 것이다.
- weeklynews — 이 파서로 정부/공공기관 공고 첨부문서를 처리하는 서비스: https://wknews.vercel.app
- shinkangteam (조직): https://github.com/shinkangteam
위 두 링크는 추후 커스텀 도메인으로 교체될 수 있다. 이 README에서 두 프로젝트를 가리키는 URL은 이 섹션에만 있다.
MIT — 자세한 내용은 LICENSE 참고.