Next.js 웹앱을 Electron 데스크톱 앱으로 만들기 전에 따져볼 것

사내 웹 도구를 쓰다 보면 어느 순간 "이거 그냥 데스크톱 앱으로 만들면 안 되나"라는 말이 나옵니다.
브라우저가 막는 기능이 하나 걸렸거나, 서버 없이 혼자 돌아가면 좋겠다는 생각에서 출발하죠.

Next.js + Prisma로 만든 웹앱을 Electron + SQLite 데스크톱 앱으로 옮기는 걸 실제로 검토하면서
정리한 판단 기준을 공유합니다. 결론부터 말하면 기술적으로는 가능하지만, 대부분의 경우
데스크톱 앱은 답이 아닙니다.

왜 이 주제가 중요한가

데스크톱 앱 전환은 되돌리기 비싼 결정입니다. 빌드 파이프라인, 코드 서명, 자동 업데이트 배포,
플랫폼별 QA가 한꺼번에 딸려 옵니다. 그런데 전환을 검토하게 만든 동기는 의외로 작은 경우가 많습니다.

우리 경우의 발단은 클립보드였습니다.

await navigator.clipboard.readText()   // 실패
await navigator.clipboard.writeText()  // 성공

브라우저는 클립보드 읽기를 보안 컨텍스트(https 또는 localhost)에서만 허용합니다.
쓰기는 되는데 읽기만 막히는 이 비대칭 때문에, http로 서빙되던 내부 도구에서 "붙여넣기" 기능이
동작하지 않았습니다.

여기서 선택지가 갈립니다. https로 옮기거나, 브라우저를 벗어나거나.
후자를 고르기 전에 아래 세 가지를 먼저 따져보길 권합니다.

핵심 개념

1. 「오프라인」은 두 가지 뜻이다

데스크톱 앱 논의에서 가장 자주 섞이는 개념입니다. 요구사항을 받으면 이 둘 중 어느 쪽인지부터
확인해야 합니다.

	중앙 서버 없이 (로컬 DB)	인터넷 없이 (완전 격리)
데이터	내 PC 안 SQLite	내 PC 안 SQLite
지도 SDK	정상	표시 안 됨
외부 API 호출	정상	불가
외부 검색·보강	정상	불가

외부 API로 데이터를 모으는 성격의 도구라면, 인터넷을 끊는 순간 수집 도구가 아니라 뷰어가 됩니다.
지도 타일을 미리 받아 넣는 방법이 없지는 않지만, 그건 "오프라인 지도 뷰어"라는 별도 프로젝트입니다.

현실적으로 요구사항의 90%는 앞쪽 열입니다. 중앙 서버 의존만 끊고 인터넷은 그대로 쓰는 것.
이 경우 기능을 하나도 잃지 않습니다.

2. Prisma + SQLite에는 못 쓰는 기능이 있다

PostgreSQL 스키마를 그대로 SQLite로 옮길 수 있다고 가정하면 안 됩니다.
100개 규모의 모델을 가진 스키마를 실제로 세어보고 확인한 제약입니다.

• enum 미지원 → 전부 String + 기본값으로 풀어야 합니다. 타입 안전성이 앱 레이어로 내려옵니다
• 스칼라 배열(String[]) 미지원 → JSON 문자열이나 별도 관계 테이블로 바꿔야 합니다
• Unsupported() 타입 불가 → pgvector 같은 확장 의존 컬럼은 통째로 포기해야 합니다. 벡터 검색 기능이 있다면 그대로 사라집니다

앱 전체를 옮기는 건 이 셋을 전부 감수한다는 뜻입니다.
범위를 한 화면으로 좁히면 부담이 급격히 줄어듭니다 — 우리 경우 enum 26개가 2개로, 배열 8개가 1개로 줄었습니다.

3. 드라이버 어댑터가 패키징 난이도를 바꾼다

Electron 배포에서 Prisma가 성가신 진짜 이유는 플랫폼별 Rust 쿼리 엔진 바이너리입니다.
win/mac/linux마다 다른 파일을 번들에 포함해야 하고, 빠뜨리면 빌드가 아니라 실행 시점에 터집니다.

@prisma/adapter-better-sqlite3

드라이버 어댑터를 쓰면 이 엔진 없이 동작합니다. 전환을 "검토할 만하다"고 판단한 근거가
사실상 이것 하나였습니다. 데스크톱 패키징을 고민 중이라면 이 옵션의 존재는 알고 있어야 합니다.

실제 적용 포인트

Next.js를 이미 output: "standalone" 으로 빌드하고 있다면 구조는 단순합니다.

Electron 앱
 ├ main    : Next standalone 서버를 앱 내부에서 기동 (127.0.0.1:고정포트)
 ├ window  : 그 주소를 로드
 └ SQLite  : app.getPath("userData")/app.db
외부 인터넷 → 각종 오픈 API

서버 코드를 다시 쓰는 게 아니라 실행 위치만 사용자 PC로 옮기는 것이라, API 라우트와
화면 코드는 대부분 그대로 살아남습니다. 바뀌는 건 스키마와 배포 방식입니다.

주의할 점

외부 SDK의 도메인 화이트리스트에 로컬 주소를 등록해야 합니다.
지도 SDK를 비롯한 상당수 JS SDK는 Referer로 허용 도메인을 검사합니다. 데스크톱 앱은
http://127.0.0.1:포트 로 뜨기 때문에, 콘솔의 「웹 서비스 URL」에 이 주소를 등록하지 않으면
앱은 정상인데 지도만 빈 화면이 됩니다. 원인 찾기 어려운 유형의 실패입니다.

포트가 매 실행마다 바뀌면 등록 자체가 불가능하므로 고정 포트를 써야 합니다.

API 키를 앱에 하드코딩하면 안 됩니다. Electron 배포 파일은 압축 해제만으로 내용이 보입니다.
앱 내부에서 키를 입력받아 로컬 DB에 저장하는 설정 화면이 반드시 필요합니다.

코드 서명 비용을 빼먹지 마세요. macOS는 공증(Apple Developer Program 연 $99) 없이는
Gatekeeper가 실행을 막고, Windows는 서명 없이 배포하면 SmartScreen 경고가 뜹니다.
혼자 쓸 때는 우회할 수 있지만, 팀에 배포하는 순간 매번 설명해야 하는 비용이 됩니다.

데이터가 PC에 갇힙니다. 서버 DB의 다른 테이블과 연결되던 기능(예: 수집한 데이터를 사내
관리 시스템에 등록)은 갈 곳이 없어집니다. CSV 내보내기로 끝낼지, 관련 모델을 함께 옮길지,
나중에 서버로 동기화할지 — 이건 기술 문제가 아니라 업무 흐름 설계 문제입니다.

듀오랩스가 보는 관점

전환 동기가 "브라우저가 막는 기능" 또는 "앱처럼 쓰고 싶다" 라면, https 적용이 압도적으로 저렴합니다.

• 클립보드 읽기를 포함한 보안 컨텍스트 제약이 한 번에 해결됩니다
• Chrome의 「앱으로 설치」(PWA)로 주소창 없는 독립 창을 당일 확보할 수 있습니다
• 빌드, 코드 서명, 업데이트 배포가 전부 필요 없습니다
• 스키마를 건드리지 않으므로 기존 기능이 하나도 죽지 않습니다

Electron이 값을 하는 건 트레이 상주, 전역 단축키, 다중 창 관리, 로컬 파일 시스템 접근,
네트워크가 끊겨도 유지돼야 하는 데이터 — 웹으로는 구조적으로 불가능한 요구가 있을 때입니다.

정리하면 이렇습니다.

• 데스크톱 전환은 기술적으로 가능하고, 드라이버 어댑터 덕분에 예상보다 수월합니다
• 다만 「오프라인」의 정의가 결론을 통째로 바꿉니다. 인터넷까지 끊으면 도구가 뷰어가 됩니다
• 동기가 작은 브라우저 제약이라면 도메인과 인증서를 붙이는 게 먼저입니다
• Electron은 웹으로 구조적으로 못 하는 요구가 생겼을 때 꺼내는 카드입니다

가장 비싼 실수는 작은 제약 하나를 해결하려고 배포 파이프라인 전체를 새로 만드는 것입니다.
전환을 검토할 때는 "무엇이 안 되는가"보다 "그게 정말 웹으로는 안 되는가" 를 먼저 물어보세요.