@ohah/hwpjs

HWP parser for Node.js, Web, and React Native

한글과컴퓨터의 한/글 문서 파일(.hwp)을 읽고 파싱하는 라이브러리입니다. Rust로 구현된 핵심 로직을 Node.js, Web, React Native 환경에서 사용할 수 있도록 제공합니다.

설치

npm install @ohah/hwpjs
# 또는
yarn add @ohah/hwpjs
# 또는
pnpm add @ohah/hwpjs
# 또는
bun add @ohah/hwpjs

사용법

CLI (Command Line Interface)

명령줄에서 직접 HWP 파일을 변환할 수 있습니다:

# 전역 설치
npm install -g @ohah/hwpjs

# JSON 변환
hwpjs to-json document.hwp -o output.json --pretty

# Markdown 변환
hwpjs to-markdown document.hwp -o output.md --include-images

# PDF 변환 (폰트 디렉터리 지정 권장)
hwpjs to-pdf document.hwp -o output.pdf --font-dir ./fonts
# 이미지 미포함 PDF
hwpjs to-pdf document.hwp -o output.pdf --font-dir ./fonts --no-embed-images

# 파일 정보 확인
hwpjs info document.hwp

# 이미지 추출
hwpjs extract-images document.hwp -o ./images

# 배치 변환
hwpjs batch ./documents -o ./output --format json --recursive
# 배치 PDF 변환
hwpjs batch ./documents -o ./output --format pdf --font-dir ./fonts

더 자세한 내용은 CLI 가이드를 참고하세요.

Node.js

import { readFileSync } from 'fs';
import { toJson, toMarkdown, toPdf, fileHeader } from '@ohah/hwpjs';

// HWP 파일 읽기
const fileBuffer = readFileSync('./document.hwp');

// PDF로 변환 (font_dir에 TTF/OTF 폰트 디렉터리 지정)
const pdfBuffer = toPdf(fileBuffer, {
  font_dir: './fonts',
  embed_images: true,
});
require('fs').writeFileSync('./output.pdf', pdfBuffer);

// JSON으로 변환
const jsonString = toJson(fileBuffer);
const document = JSON.parse(jsonString);
console.log(document);

// Markdown으로 변환
const { markdown, images } = toMarkdown(fileBuffer, {
  image: 'blob', // 또는 'base64'
  use_html: true,
  include_version: true,
  include_page_info: true,
});

// FileHeader만 추출
const headerString = fileHeader(fileBuffer);
const header = JSON.parse(headerString);
console.log(header);

Web (Browser)

import { toJson, toMarkdown } from '@ohah/hwpjs';

// File input에서 HWP 파일 읽기
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  const arrayBuffer = await file.arrayBuffer();
  const uint8Array = new Uint8Array(arrayBuffer);

  // JSON으로 변환
  const jsonString = toJson(uint8Array);
  const document = JSON.parse(jsonString);

  // Markdown으로 변환 (base64 이미지 포함)
  const { markdown } = toMarkdown(uint8Array, {
    image: 'base64',
  });

  // 결과 표시
  document.getElementById('output').innerHTML = markdown;
});

React Native

import { toJson, toMarkdown, toPdf } from '@ohah/hwpjs';
import * as FileSystem from 'expo-file-system';

// HWP 파일 읽기
const fileUri = 'file:///path/to/document.hwp';
const base64 = await FileSystem.readAsStringAsync(fileUri, {
  encoding: FileSystem.EncodingType.Base64,
});
const uint8Array = Uint8Array.from(atob(base64), c => c.charCodeAt(0));

// JSON으로 변환
const jsonString = toJson(uint8Array);
const document = JSON.parse(jsonString);

// Markdown으로 변환
const { markdown, images } = toMarkdown(uint8Array, {
  image: 'blob',
});

// PDF로 변환 (한글 폰트 경로 필요)
// 패키지에 포함된 폰트: node_modules/@ohah/hwpjs/fonts/ 를 앱 문서 디렉터리 등에 복사한 뒤 그 경로를 넘기세요.
const pdfBuffer = toPdf(uint8Array, {
  fontDir: '/path/to/fonts', // NotoSansKR-Regular.ttf 가 있는 디렉터리
  embedImages: true,
});
await FileSystem.writeAsStringAsync(
  `${FileSystem.documentDirectory}output.pdf`,
  Buffer.from(pdfBuffer).toString('base64'),
  { encoding: FileSystem.EncodingType.Base64 }
);

API

toJson(data: Buffer | Uint8Array): string

HWP 파일을 JSON 문자열로 변환합니다.

Parameters:

• data: HWP 파일의 바이트 배열 (Buffer 또는 Uint8Array)

Returns:

• JSON 문자열 (파싱된 HWP 문서)

Example:

const fileBuffer = readFileSync('./document.hwp');
const jsonString = toJson(fileBuffer);
const document = JSON.parse(jsonString);

toMarkdown(data: Buffer | Uint8Array, options?: ToMarkdownOptions): ToMarkdownResult

HWP 파일을 Markdown 형식으로 변환합니다.

Parameters:

• data: HWP 파일의 바이트 배열 (Buffer 또는 Uint8Array)
• options: 변환 옵션 (선택)
  • image: 이미지 형식 ('base64' 또는 'blob', 기본값: 'blob')
  • use_html: HTML 태그 사용 여부 (기본값: false)
  • include_version: 버전 정보 포함 여부 (기본값: false)
  • include_page_info: 페이지 정보 포함 여부 (기본값: false)

Returns:

• ToMarkdownResult 객체:
  • markdown: Markdown 문자열
  • images: 이미지 데이터 배열 (blob 형식인 경우)

Example:

// Base64 이미지 포함
const { markdown } = toMarkdown(fileBuffer, {
  image: 'base64',
  use_html: true,
});

// Blob 이미지 (별도 배열로 반환)
const { markdown, images } = toMarkdown(fileBuffer, {
  image: 'blob',
});
// images 배열에서 이미지 데이터 사용
images.forEach(img => {
  console.log(`Image ${img.id}: ${img.format}, ${img.data.length} bytes`);
});

fileHeader(data: Buffer | Uint8Array): string

HWP 파일의 FileHeader만 추출하여 JSON 문자열로 반환합니다.

Parameters:

• data: HWP 파일의 바이트 배열 (Buffer 또는 Uint8Array)

Returns:

• JSON 문자열 (FileHeader 정보)

Example:

const fileBuffer = readFileSync('./document.hwp');
const headerString = fileHeader(fileBuffer);
const header = JSON.parse(headerString);
console.log(header.version);

toPdf(data: Buffer | Uint8Array, options?: ToPdfOptions): Buffer

HWP 파일을 PDF 바이트로 변환합니다. 한글 등이 포함된 문서는 font_dir에 한글 지원 폰트(예: Noto Sans KR)를 넣어야 합니다.

Parameters:

• data: HWP 파일의 바이트 배열 (Buffer 또는 Uint8Array)
• options: 변환 옵션 (선택)
  • font_dir: TTF/OTF 폰트가 있는 디렉터리 경로 (신뢰할 수 있는 경로만 사용)
  • embed_images: PDF에 이미지 임베드 여부 (기본값: true)

Returns:

• PDF 파일 내용 (Buffer)

Example:

const pdfBuffer = toPdf(fileBuffer, {
  font_dir: './fonts',
  embed_images: true,
});
require('fs').writeFileSync('./output.pdf', pdfBuffer);

예제

더 자세한 예제는 예제 디렉토리를 참고하세요.

• Node.js 예제
• Web 예제
• React Native 예제

지원 플랫폼

Node.js

• Windows (x64, x86, arm64)
• macOS (x64, arm64)
• Linux (x64)

Web

• WASM (WebAssembly)

React Native

• iOS
• Android

라이선스

MIT