The TypeScript toolkit for reading, editing, and automating Korean word processor (HWPX) documents.
HWPX is the modern XML-based format used by Hangul (한글), the dominant word processor in Korea — used by government, education, and enterprise. hwpx-ts gives you full programmatic access to these documents in TypeScript/JavaScript.
- Only TypeScript HWPX library — no native binaries, no Python, no Java dependency
- Works everywhere — Node.js, browsers, serverless (Cloudflare Workers, Vercel Edge)
- AI/Agent-ready — built-in MCP server for Claude, llms.txt for LLM discovery
- Zero-config —
npm installand start coding in 30 seconds
Pick the path that matches your goal:
- Use as a library
npm install @ubermensch1218/hwpxcore
- Connect to an AI agent (MCP)
npx @ubermensch1218/hwpx-mcp
- Contribute to this monorepo
corepack enable pnpm install pnpm --filter @ubermensch1218/hwpxcore typecheck pnpm --filter @ubermensch1218/hwpxcore test pnpm --filter @ubermensch1218/hwpxcore build
- Canonical TypeScript onboarding lives in this README and package READMEs under
packages/ docs/is currently a Sphinx site with Python-oriented workflows; use package READMEs for TypeScript-first usage- If you want one-step scaffolding, run
npx @ubermensch1218/hwpx-cli init
npm install @ubermensch1218/hwpxcore
import { HwpxDocument } from "@ubermensch1218/hwpxcore"; const buffer = await fetch("document.hwpx").then((r) => r.arrayBuffer()); const doc = await HwpxDocument.open(new Uint8Array(buffer)); console.log(doc.text); // all text content console.log(doc.tables); // all tables console.log(doc.sections.length); // section count
import { HwpxDocument, loadSkeletonHwpx } from "@ubermensch1218/hwpxcore"; const doc = await HwpxDocument.open(loadSkeletonHwpx()); doc.addParagraph("Hello, HWPX!"); doc.addParagraph("Second paragraph."); doc.replaceText("Hello", "Hi"); // Save const bytes = await doc.saveToBuffer(); // Uint8Array const blob = await doc.saveToBlob(); // Blob (for browsers) await doc.saveToPath("./output.hwpx"); // Node.js file path
const para = doc.sections[0].paragraphs[0]; para.addTable(2, 3); const table = para.tables[0]; table.setCellText(0, 0, "Item"); table.setCellText(0, 1, "Qty"); table.setCellText(0, 2, "Price"); table.setCellText(1, 0, "Widget"); table.setCellText(1, 1, "10"); table.setCellText(1, 2, "100,000");
doc.addImage(imageBytes, { mediaType: "image/png", widthMm: 100, heightMm: 80, });
const charPrId = doc.ensureRunStyle({ bold: true, italic: true, fontSize: 14 }); const paraPrId = doc.ensureParaStyle({ alignment: "center" });
npx @ubermensch1218/hwpx-cli hwpx-to-md document.hwpx
npx @ubermensch1218/hwpx-cli read document.hwpxnpx @ubermensch1218/hwpx-mcp
Claude Desktop / Claude Code config:
{
"mcpServers": {
"hwpx": {
"command": "npx",
"args": ["@ubermensch1218/hwpx-mcp"]
}
}
}MCP tools provided: hwpx_read, hwpx_export, hwpx_extract_xml, hwpx_info
Set up everything at once — install dependencies, configure MCP, and you're ready:
npx @ubermensch1218/hwpx-cli init
This will:
- Install
@ubermensch1218/hwpxcoreinto your project - Optionally configure the HWPX MCP server for Claude Code
- Create a starter example file
| Package | Description | npm |
|---|---|---|
@ubermensch1218/hwpxcore |
Core HWPX read/edit library | npm |
@ubermensch1218/hwpxeditor |
React-based HWPX editor UI | npm |
@ubermensch1218/hwpx-mcp |
MCP server for LLM integration | - |
@ubermensch1218/hwpx-tools |
Conversion & export utilities | - |
@ubermensch1218/hwpx-cli |
CLI tool | - |
npm install @ubermensch1218/hwpxeditor react react-dom
import { Editor } from "@ubermensch1218/hwpxeditor"; export default function App() { return <Editor />; }
- ZIP save writes
mimetypeas first entry with STORE compression (HWPX spec compliance) - XML serialization preserves HWPX namespace prefixes (
hp,hs,hc,hh) - Graceful fallback for non-standard container/manifest with warning handlers
- See
llms.txtfor a concise, machine-readable API reference - See
llms-full.txtfor complete API documentation - MCP server enables direct HWPX manipulation from Claude and other LLM agents
- GitHub conversion survey:
docs/github-hwpx-conversion-survey-2026年03月04日.md
pnpm install # Test, typecheck, build pnpm --filter @ubermensch1218/hwpxcore test pnpm --filter @ubermensch1218/hwpxcore typecheck pnpm --filter @ubermensch1218/hwpxcore build
Non-Commercial License. See LICENSE for details.
If hwpx-ts is useful to you, please consider giving it a star on GitHub!