앱스인토스 미니앱 개발 환경 세팅, 윈도우에서 막히는 네 곳

새 플랫폼은 첫 빌드까지가 제일 깁니다.

앱스인토스도 문서대로 따라 하면 되는데, 윈도우에서는 네 군데가 그냥 막힙니다.

이번 포스팅에서는 그 네 곳과 각각의 해결 방법을 정리해 보도록 하겠습니다.

먼저 확인할 것

2026년 8월 윈도우 11 에서 확인한 내용입니다. Granite 기반 리액트 네이티브 미니앱 기준입니다.

맥이나 리눅스에서는 세 번째 항목이 해당하지 않습니다.

그러면 프로젝트를 만드는 첫 명령부터 보겠습니다.

프로젝트 생성 명령이 조용히 멈춥니다

생성기가 대화형 프롬프트를 띄우는데, 터미널이 TTY 가 아니면 입력을 못 받고 그대로 섭니다.

에디터에 딸린 터미널이나 스크립트 안에서 돌릴 때 걸립니다.

위치 인자와 --tools 를 둘 다 주면 프롬프트 없이 지나갑니다.

npx create-granite-app@latest my-app --tools eslint-prettier

하나만 주면 남은 질문을 하려고 다시 멈춥니다. 둘 다 주는 게 요령입니다.

Node 20.18 에서는 빌드가 되지 않습니다

버전이 조금 낮은 정도가 아니라 아예 안 됩니다.

@granite-js/plugin-core 가 CommonJS 인데 ESM 전용 패키지를 require 하기 때문입니다.

ESM 을 require 하는 기능은 Node 20.19 와 22.12 부터 기본으로 켜집니다. 그 아래에서는 방법이 없습니다.

nvm-windows 를 쓰신다면 비트 수까지 적어 주셔야 합니다.

nvm install 22.23.2 64
nvm use 22.23.2

nvm install 22 라고만 하면 arm64 를 찾다가 실패합니다.

윈도우용 hermesc 는 패키지에 들어 있지 않습니다

이게 가장 늦게 발견되는 함정입니다.

hermes-compiler 패키지에는 리눅스와 맥용 바이너리만 있습니다. 리액트 네이티브 0.84 의 sdks/ 에도 윈도우용은 없습니다.

그런데 개발 서버와 JS 번들링은 hermesc 없이도 잘 돕니다. 막히는 건 배포용 번들을 만들 때뿐입니다.

그래서 며칠 동안 잘 개발하다가 제출 직전에 처음 만나게 됩니다.

플러그인의 폴백 순서상 아래 한 줄이면 해결됩니다.

npm i -D hermes-engine

이 패키지에 win64-bin/hermesc.exe 가 들어 있기 때문입니다.

AbortSignal 이 두 번 선언돼 타입이 충돌합니다

리액트 네이티브 0.84 는 AbortSignal 을 두 곳에서 선언합니다.

그래서 AbortSignal.timeout() 을 부를 수 없고, controller.signal 을 fetch 에 넘길 때도 타입이 맞지 않습니다.

런타임은 멀쩡하고 타입만 어긋난 상태라, 경계에서 한 번만 캐스팅해 줍니다.

const controller = new AbortController();
const res = await fetch(url, {
  signal: controller.signal as unknown as RequestInit['signal'],
});

타입 단언을 앱 곳곳에 뿌리지 않고 통신 함수 한 곳에만 두시는 편이 낫습니다. 나중에 라이브러리가 고쳐지면 지울 자리가 분명하기 때문입니다.

세팅이 끝났는지 확인하는 법

개발 서버가 뜨는 것만으로는 끝난 게 아닙니다. 앞서 본 hermesc 가 그래서 늦게 걸립니다.

아래 네 가지가 순서대로 통과해야 진짜 끝입니다.

node -v            # 20.19 이상 또는 22.12 이상
npx tsc --noEmit   # 타입
npm run build      # granite build — 번들
npx ait build      # 제출물 .ait

마지막 줄까지 돌려 보시는 걸 권합니다. 제출물을 만드는 명령이 따로 있는데, 그 이야기는 따로 한 편으로 다루겠습니다.

다섯 줄로 줄이면

1. 생성 명령은 위치 인자와 --tools 를 같이 줍니다.
2. Node 는 20.19 또는 22.12 이상이어야 합니다. 그 아래는 우회로가 없습니다.
3. nvm-windows 는 nvm install 22.23.2 64 처럼 비트 수까지 적습니다.
4. 윈도우는 npm i -D hermes-engine 을 넣어야 배포 번들이 나옵니다.
5. AbortSignal 타입 충돌은 통신 함수 한 곳에서만 캐스팅합니다.

지금 개발 서버만 확인하고 계신다면, 배포 번들까지 한 번 뽑아 보시는 건 어떨까요?

그러면 오늘도 모두 스테이블 하세요.

---

만든 것들

• 토스 미니앱 모음. 이 환경으로 만든 앱들입니다
• 프리랜서 서랍. 견적서·거래명세서·영수증을 브라우저에서 바로
• 루티니. 3분으로 쪼개는 루틴 타이머 (안드로이드)