🎯 목표
일반적인 React/Vite 프로덕션 빌드를 독립 실행형, 고도로 사용자 정의된 네이티브 Windows .exe 인스톨러로 변환합니다. 이 래퍼는 표준 OS 창 크롬을 우회하여 결정론적이고 시네마틱한 5단계 인스톨러 마법사 인터페이스를 제공합니다.
🛠️ 핵심 엔지니어링 모듈
1. 생명주기 가로채기 및 창 스타일링 (electron.js)
고정된 레이아웃 창 크기($760 \times 480\text{px}$)를 하드코딩으로 초기화하며, 다음과 같은 엄격한 네이티브 속성을 적용합니다:
frame: false(모든 네이티브 OS 창 테두리/경계 비활성화)resizable: false(크기 고정)transparent: true(사용자 정의 웹 스타일링을 위한 투명 배경 활성화)
preload.js를 통해 격리되고 안전한 비동기 IPC(프로세스 간 통신) 아키텍처를 노출합니다. 이는 백그라운드 런타임과 React 렌더러 계층 간에 샌드박스 액세스 안전 충돌 없이 데이터를 깔끔하게 전달합니다.
2. 시스템 자산 배포 (Node.js 백그라운드 계층)
- 디렉터리 매핑:
fs-extra를 사용하여 안전하게 대상 폴더를 빌드하기 위해 워크스페이스 문자열 경로를 동적으로 파싱합니다. - 바로가기 링크 주입: 백그라운드 자식 프로세스를 트리거하여 Windows PowerShell 명령을 실행하고 사용자 바탕화면 환경에 네이티브
.lnk바로가기를 직접 생성합니다. - OS 앱 목록 레지스트리 등록: 로컬 머신 레지스트리 인덱스 경로에 필수 소프트웨어 애플리케이션 텔레메트리를 직접 주입합니다:
HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\[AppName]DisplayName,DisplayIcon, 설치 디렉터리 대상 및 운영 제거 문자열 훅이 올바르게 설정되어 앱을 Windows 앱 및 기능 유틸리티에 깔끔하게 바인딩합니다.
🎨 프론트엔트 아키텍처 및 단계 머신 (React)
인스톨러 인터페이스는 Tailwind CSS를 사용하여 깊고 미니멀한 슬레이트 블루 원색(#0a0f1d, #111827)으로 스타일링된 결정론적 5단계 React 상태 머신을 실행합니다:
- 환영 온보딩 단계: 소프트웨어 버전과 구성 플래그를 표시하는 미니멀한 타이포그래피 헤더.
- 사용자 정의 테마 디렉터리 탐색기: 표준 Windows 네이티브 파일 탐색기를 우회하여 웹 애플리케이션의 DOM 컨텍스트 내에서 직접 실행되는 사용자 정의 폴더 선택 대화 상자 모달.
- 워크스페이스 토글: 바탕화면 바로가기 파일 생성 및 배포를 제어하는 상태 저장 체크박스 컴포넌트(기본값 ON).
- 시네마틱 진행률 화면 단계: 파일 시스템 복사 실행 시간과 일치하는 정확히 3.5초 선형 진행률 애니메이션에 동기화된 부드러운 CSS 마이크로 상호작용 및 애니메이션을 렌더링하는 풀 블리드, 테두리 없는 레이아웃.
- 완료 선택: 표준 종료 트리거 또는 "애플리케이션 실행"을 통한 즉시 시스템 실행을 제공하는 이중 분기 종료 화면.
🖼️ 애플리케이션 로고 해상도 프로토콜
인스톨러는 고충실도 그래픽 프리미티브(icon.ico 및 투명한 logo.png)가 필요합니다. 누락된 시각적 구성 요소는 다음 폴백 시퀀스를 사용하여 해결합니다:
- 프로토콜 A: 사용자 제공 브랜딩 (고급): 마법사 구성 화면을 통해 사용자 정의 자산이 제공되면 파일 객체를 캡처하고, 크기를 검증하며, UI 계층으로 스트리밍한 후
.ico변형을 최종 실행 파일 헤더 메타데이터에 직접 컴파일합니다. - 프로토콜 B: AI 기반 컨텍스트 폴백 (제로 지식): 브랜딩이 제공되지 않으면 애플리케이션 메타데이터(이름, 설명, 산업 분야)를 파싱합니다. 벡터 또는 저장소 조회를 수행하여 깔끔하고 기하학적이며 미니멀한 오픈 소스 아이콘을 추출합니다. 가드레일: 혼란스럽고 장식적이며 직설적인 클립아트 디자인은 절대 금지합니다. 추상적이고 고급스러운 벡터 구조만 유효합니다.
⚠️ 제약 조건 및 가드레일
- 상대 자산 주소 지정: 빌드 구성 내의 모든 출력 자산이 상대 경로(
./static/...)를 사용하도록 보장합니다. 절대 웹 해상도 참조는 패키지된 파일 시스템 내에서 깨져서 빈 흰색 화면 런타임 오류를 유발합니다. - 보안 격리: 항상
nodeIntegration: false및contextIsolation: true를 활성 상태로 유지합니다. 모든 백그라운드 플랫폼 작업은contextBridge계층을 통해 안전하게 전환되어야 합니다.
📝 예제
예제: package.json에 매니페스트 대상 주입
"build": {
"appId": "com.whyskai.custominstaller",
"productName": "WhyskAI-CustomInstaller-Maker",
"win": {
"target": ["nsis"],
"icon": "assets/icon.ico"
},
"nsis": {
"oneClick": false,
"allowToChangeInstallationDirectory": true,
"installerIcon": "assets/icon.ico",
"uninstallerIcon": "assets/icon.ico",
"createDesktopShortcut": true,
"runAfterFinish": true
}
}