React·Vue에서 한글스크립트 사용하기
이 가이드는 @uiwwsw/hangulscript@0.8.0 문법과 공통 Vite 플러그인을 사용합니다.
화면과 상태는 React/Vue로 만들고 계산·조건·검증 함수를 .hgs에 작성합니다.
데모의 숫자입력·버튼·보여주기는 데모 UI 실행 환경의 API이며 React/Vue 컴포넌트로 자동 변환되지 않습니다.
완성된 예제를 먼저 실행하기
Node.js 24에서 검증했습니다. 예제의 Vite는 Node.js ^20.19.0 || >=22.12.0을 요구합니다.
git clone https://github.com/uiwwsw/hangulscript.git
cd hangulscript/examples/react-vite
npm ci
npm run dev
Vue는 같은 저장소의 examples/vue-vite에서 npm ci와 npm run dev를 실행하세요.
터미널에 표시된 localhost 주소를 열고 가격 10000, 할인율 20을 입력한 뒤 계산하기를 누르면 결제 금액 8,000원이 표시됩니다.
개발 서버는 loopback에서 실행하며, 포트가 사용 중이면 터미널에 표시된 실제 주소를 사용하세요.
배포할 정적 파일은 각 예제에서 npm run build로 만들고 npm run preview로 확인합니다.
기존 Vite 프로젝트에 설치하기
npm install --save-dev @uiwwsw/hangulscript@^0.8.0
React/Vue와 해당 Vite 플러그인은 기존 프로젝트에 설치돼 있다고 가정합니다. 새 프로젝트는 위의 완성된 예제를 사용할 수 있습니다.
React의 vite.config.js:
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import hangulscript from '@uiwwsw/hangulscript/vite';
export default defineConfig({ plugins: [hangulscript(), react()] });
Vue의 vite.config.js:
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import hangulscript from '@uiwwsw/hangulscript/vite';
export default defineConfig({ plugins: [hangulscript(), vue()] });
공통 로직 작성하기
두 예제의 src/discount.hgs는 동일합니다. 함수와 조건을 한글 문장으로 작성하고 ESM export로 내보냅니다.
결제금액(가격: 숫자, 할인율: 숫자)를 정의한다:
만약 !Number.isFinite(가격) || !Number.isFinite(할인율) || 가격 < 0 || 할인율 < 0 || 할인율 > 100 이라면:
돌려주기 "가격은 0 이상, 할인율은 0~100 사이로 입력하세요"
돌려주기 가격 - 반올림(가격 * 할인율 / 100)
결제금액을 공개한다
React에서 호출하기
src/main.jsx에서 함수를 가져와 submit 이벤트에 연결합니다. 입력과 결과 상태는 React가 관리합니다.
import { useState } from 'react';
import { createRoot } from 'react-dom/client';
import { 결제금액 } from './discount.hgs';
import './style.css';
function App() {
const [가격, 가격변경] = useState('10000');
const [할인율, 할인율변경] = useState('20');
const [결과, 결과변경] = useState(null);
function 계산(event) {
event.preventDefault();
결과변경(결제금액(Number(가격), Number(할인율)));
}
return <main>
<h1>React + 한글스크립트</h1>
<p>화면은 React, 계산과 검증은 discount.hgs에서 처리합니다.</p>
<form onSubmit={계산}>
<label>가격 (원)<input type="number" min="0" required value={가격} onChange={e => 가격변경(e.target.value)} /></label>
<label>할인율 (%)<input type="number" min="0" max="100" step="any" required value={할인율} onChange={e => 할인율변경(e.target.value)} /></label>
<button type="submit">계산하기</button>
</form>
<output aria-live="polite">{결과 === null ? '입력 후 계산하기를 눌러 주세요.' : typeof 결과 === 'number' ? `결제 금액: ${결과.toLocaleString('ko-KR')}원` : 결과}</output>
</main>;
}
createRoot(document.getElementById('app')).render(<App />);
Vue에서 호출하기
src/App.vue에서 같은 함수를 가져와 submit 이벤트에 연결합니다. 반응형 상태는 Vue가 관리합니다.
<script setup>
import { ref } from 'vue';
import { 결제금액 } from './discount.hgs';
const 가격 = ref(10000);
const 할인율 = ref(20);
const 결과 = ref(null);
function 계산() {
결과.value = 결제금액(Number(가격.value), Number(할인율.value));
}
</script>
<template>
<main>
<h1>Vue + 한글스크립트</h1>
<p>화면은 Vue, 계산과 검증은 discount.hgs에서 처리합니다.</p>
<form @submit.prevent="계산">
<label>가격 (원)<input v-model="가격" type="number" min="0" required /></label>
<label>할인율 (%)<input v-model="할인율" type="number" min="0" max="100" step="any" required /></label>
<button type="submit">계산하기</button>
</form>
<output aria-live="polite">{{ 결과 === null ? '입력 후 계산하기를 눌러 주세요.' : typeof 결과 === 'number' ? `결제 금액: ${결과.toLocaleString('ko-KR')}원` : 결과 }}</output>
</main>
</template>
TypeScript 프로젝트와 빌드 범위
| 방식 | 제공 범위 | 적합한 용도 |
|---|---|---|
Vite 플러그인으로 .hgs import |
JavaScript 변환, Vite 개발 서버·빌드 연동 | React/Vue JavaScript 프로젝트 |
ksc build 후 .js import |
타입 검사, JavaScript와 .d.ts 생성 |
TypeScript 프로젝트·라이브러리 |
| 온라인 데모의 화면 함수 | 격리 실행, 입력창·버튼·콘솔 결과 | 설치 없는 도구 만들기·코드 공유 |
0.7.0부터 Vite 플러그인은 구문과 타입을 검사하고 오류가 있으면 빌드를 중단합니다. 선언 생성·디버깅용 원본 .hgs 소스맵은 제공하지 않습니다.
TypeScript에서 .hgs 파일을 직접 가져오면 모듈 타입을 찾지 못할 수 있습니다.
외부 TypeScript 소비자에게 선언을 제공하려면 다음처럼 빌드한 .js를 가져오세요. 인접한 .d.ts를 TypeScript가 읽습니다.
npx ksc build src/discount.hgs
import { 결제금액 } from './discount.js';
const 결과 = 결제금액(10000, 20); // number | string
이 방식은 .hgs를 수정할 때 다시 빌드해야 합니다. 명시적인 타입과 추론 가능한 값은 검사하며, any 값에 대한 검사는 제한됩니다.
Next.js·Webpack처럼 Vite를 사용하지 않는 환경에서도 미리 만든 .js·.d.ts를 가져오는 방식을 사용할 수 있습니다. 전용 Next.js·Webpack 플러그인은 제공하지 않습니다.