es-hangul

초성 검색·조사 처리·한글 문자열 처리를 위한 Toss의 모던 JavaScript 라이브러리

npm install es-hangul

es-hangul은 Toss가 공개한 한글 처리 JavaScript 라이브러리입니다. 초성 추출, 초성 검색, 조사 붙이기 같은 한국어 UI와 검색에서 자주 필요한 문자열 처리를 모던 API로 제공합니다. ESM/CJS export와 TypeScript 타입을 포함하고, 브라우저에서 필요한 코드만 내려받는 사용을 지향합니다.

판단

이럴 때 씁니다

  • 한국어 검색 입력에서 초성 검색을 구현해야 할 때.
  • 버튼, 알림, 문장 생성에서 `을/를`, `이/가` 같은 조사를 단어에 맞게 붙여야 할 때.
  • 프론트엔드 번들에서 한글 처리 유틸만 가볍게 가져오고 싶을 때.
  • 에이전트가 한국어 UI 로직을 작성할 때 검증된 작은 API를 명시해 환각 구현을 줄이고 싶을 때.

이럴 땐 쓰지 마세요

  • 형태소 분석, 띄어쓰기 교정, 의미 검색, 번역 같은 NLP 전체를 기대하면 범위가 맞지 않습니다.
  • 영문/다국어 문자열 처리까지 한 라이브러리로 통일하려는 요구에는 너무 한국어 특화입니다.
  • 초성 검색 이상의 검색 품질, 랭킹, fuzzy matching은 별도 검색 엔진이나 로직이 필요합니다.
  • 런타임 의존성을 늘리고 싶지 않은 아주 작은 프로젝트라면 필요한 함수만 직접 구현하는 선택도 가능합니다.

차별점

  • 초성화와 조사 처리처럼 한국어 제품 UI에서 실제로 자주 필요한 함수를 작은 패키지로 제공합니다.
  • ESM import 경로와 CJS require 경로를 모두 export하고 TypeScript declaration을 포함합니다.
  • Toss/Viva Republica가 관리하는 MIT 라이선스 라이브러리라 한국어 프론트엔드 생태계에서 신뢰 신호가 분명합니다.
  • README가 `getChoseong`, `josa`처럼 바로 이해되는 API 예시를 제공해 에이전트가 한국어 UX 코드를 작성할 때 지시하기 쉽습니다.

워크플로

  1. 01`npm install es-hangul`로 패키지를 추가합니다.
  2. 02초성 검색에는 `getChoseong`을 import해 검색 대상과 입력값을 같은 기준으로 비교합니다.
  3. 03문장 생성에는 `josa(word, '을/를')`처럼 조사 후보를 넘겨 자연스러운 조사를 붙입니다.
  4. 04검색 랭킹, debounce, highlight 같은 제품 로직은 es-hangul 결과를 기반으로 별도 구현합니다.

주요 명령

명령설명
npm install es-hangulnpm으로 라이브러리를 설치합니다
import { getChoseong } from 'es-hangul'초성 추출 함수를 가져옵니다
import { josa } from 'es-hangul'조사 처리 함수를 가져옵니다
yarn test저장소 checkout에서 vitest/typecheck 기반 테스트를 실행합니다

설정

import { getChoseong, josa } from 'es-hangul'

const choseong = getChoseong('라면')
const sentence = josa('사과', '을/를') + ' 먹었습니다.'

함정

설치 전에 확인하세요

  • 패키지 자체는 작지만 한국어 형태소 분석기나 자연어 이해 모델이 아닙니다. 초성·조사 같은 문자열 유틸 범위로 봐야 합니다.
  • README 예시는 초성 검색과 조사 처리 중심입니다. 복잡한 검색 랭킹이나 오타 교정은 별도 구현이 필요합니다.
  • 서버/클라이언트 양쪽에서 쓰는 경우 ESM/CJS 번들 설정과 tree-shaking 결과를 확인해야 합니다.
  • 한국어가 아닌 다국어 처리까지 일반화하려는 목적에는 범위가 좁습니다.

직접 써본 메모

es-hangul은 거대한 AI 도구는 아니지만 한국어 제품을 만드는 개발자에게 실용성이 큽니다. 초성 검색과 조사 처리는 매번 직접 구현하면 edge case가 늘고, 에이전트가 임의로 만든 코드도 쉽게 어긋납니다. 이런 부분을 검증된 작은 라이브러리로 고정하는 가치가 있습니다.

특히 이 사이트의 dev_tools 카탈로그에서는 “에이전트가 쓸 수 있는 개발 도구”라는 관점에서 의미가 있습니다. Codex나 Claude Code에게 한국어 검색/문장 UI를 만들게 할 때 `es-hangul` API를 지정하면 불필요한 수작업 구현을 줄일 수 있습니다.

다만 범위는 좁게 봐야 합니다. 형태소 분석기나 검색 엔진이 아니라 한글 문자열 유틸입니다. 초성 추출과 조사 처리 같은 작은 문제를 정확히 푸는 도구로 쓰고, 랭킹·오타 보정·다국어 검색은 별도 계층에서 다루는 구성이 맞습니다.

비교

MarkItDown이 여러 파일을 Markdown으로 바꾸는 문서 전처리 라이브러리라면, es-hangul은 앱 내부의 한국어 문자열 처리를 담당하는 작은 런타임 라이브러리입니다. hangul-js 같은 기존 한글 처리 라이브러리와 같은 문제를 다루지만, 현대 bundler와 ESM/TypeScript 사용성을 더 전면에 둡니다.

최근 변경

2.4.0에서 중성·종성 추출 함수와 getChoseong의 비한글 유지 옵션을 추가하고 비한글 혼합 조합과 발음 표준화 문제를 수정했다.

공식 변경 내역