로컬 XLSX (Excel) 파일에서 에러 콘텐츠를 가져오는 방법을 설명합니다. 외부 API나 인증 없이 간단하게 사용할 수 있습니다.

템플릿으로 빠르게 시작하기

미리 작성된 XLSX 템플릿을 다운로드하면 바로 사용할 수 있습니다. 한국어/English 시트가 포함되어 있습니다.

XLSX 템플릿 다운로드

TIP

다운로드 후 데이터를 수정하고 huh pull을 실행하세요.

---

1. XLSX 파일 작성

Excel에서 첫 번째 행을 헤더 행으로 작성합니다:

trackId	type	message	title	image	severity	actionLabel	actionType	actionTarget
ERR_LOGIN_FAILED	TOAST	로그인에 실패했습니다
ERR_SESSION_EXPIRED	MODAL	세션이 만료되었습니다	세션 만료		ERROR	다시 로그인	REDIRECT	/login
ERR_NOT_FOUND	PAGE	페이지를 찾을 수 없습니다	404	/img/404.png	INFO	홈으로	REDIRECT	/

TIP

소문자로 입력해도 CLI가 자동으로 대문자로 변환합니다. 커스텀 타입(BANNER, SNACKBAR 등)도 자유롭게 사용할 수 있습니다.

컬럼 규칙

컬럼명	필수	설명
trackId	O	에러 고유 ID (예: ERR_LOGIN_FAILED)
type	O	TOAST, MODAL, PAGE 또는 커스텀 타입
message	O	에러 메시지. 템플릿 변수 지원
title		에러 제목 (modal, page용)
image		이미지 URL (page용)
severity		INFO, WARNING, ERROR, CRITICAL 또는 커스텀 심각도
actionLabel		액션 버튼 텍스트
actionType		REDIRECT, RETRY, BACK, DISMISS 또는 커스텀 액션
actionTarget		REDIRECT 시 이동할 URL

2. 설정

.huh.config.json

{
  "source": {
    "type": "xlsx",
    "filePath": "./errors.xlsx"
  },
  "output": "./src/huh.json"
}

특정 시트를 지정하려면 sheet 옵션을 사용합니다:

{
  "source": {
    "type": "xlsx",
    "filePath": "./errors.xlsx",
    "sheet": "에러목록"
  },
  "output": "./src/huh.json"
}

sheet를 지정하지 않으면 첫 번째 시트를 사용합니다.

.huh.config.ts

import { defineConfig } from '@sanghyuk-2i/huh-cli';

export default defineConfig({
  source: {
    type: 'xlsx',
    filePath: './errors.xlsx',
    // sheet: '에러목록',  // 선택: 미지정 시 첫 번째 시트
  },
  output: './src/huh.json',
});

filePath는 상대 경로 또는 절대 경로를 사용할 수 있습니다. 상대 경로는 process.cwd() 기준으로 해석됩니다.

3. 데이터 가져오기

정상적으로 실행되면 output 경로에 JSON 파일이 생성됩니다.

참고

• .xlsx 형식만 지원합니다 (구형 .xls 형식은 지원하지 않습니다).
• 시트에는 헤더 행 + 최소 1개의 데이터 행이 있어야 합니다.
• 지정한 시트 이름이 존재하지 않으면 사용 가능한 시트 목록과 함께 에러가 표시됩니다.
• SheetJS 라이브러리를 사용합니다.