SvelteKit 3 정식 출시: 설정 통합과 오류·환경 변수 개선
SvelteKit 3.0은 2026년 10월 1일 정식 출시됐습니다. 새로운 프레임워크로 다시 시작하기보다, 익숙한 앱 구조를 유지하며 설정·타입·오류 처리의 불일치를 줄이는 릴리스입니다. Vite 설정 통합과 표준 import, 명시적 환경 변수, 렌더링 오류 처리 개선을 기존 앱의 유지보수 관점에서 살펴봅니다.
10월 11일 기준 공식 발표와 현재 문서를 확인했습니다. 8월 Release Candidate 안내는 배경 설명으로만 참고하며, 설치 명령과 최소 버전은 정식 문서를 따릅니다. remote functions는 정식 출시 범위와 구분해야 합니다.
이번 릴리스의 중심 메시지
앱을 새로 쓰기보다, 설정과 실패 경로를 명확히 해 계속 운영하기 쉬운 기반으로 옮깁니다.
이는 공식 변경을 묶은 이 글의 해석입니다. 마이그레이션 도구는 반복 수정을 줄이지만 동작 검증을 대신하지 않습니다. 새 실험 기능을 도입하는 결정도 별개입니다.
1. 사용자 기능 단위별 가치
| 기능 단위 | 주요 사용자 | 사용자가 느끼는 문제 | 업데이트 가치 | 사용자에게 와닿는 메시지 |
|---|---|---|---|---|
| Vite 설정 통합 | 설정과 빌드를 관리하는 개발자 | Kit·Vite 설정이 나뉘어 적용 위치를 찾기 어려움 | sveltekit plugin에 설정을 모음 | 빌드 설정을 한 곳에서 읽는다 |
| #lib와 TypeScript 설정 | 공유 모듈과 테스트를 관리하는 팀 | 도구마다 alias와 생성 설정을 맞춰야 함 | 표준 subpath imports와 $app/tsconfig 사용 | import와 타입 설정을 표준 도구에 맞춘다 |
| 명시적 환경 변수 | 배포·운영 담당자 | 필요한 변수·노출 범위·값 형식이 흩어져 있음 | 선언·공개 여부·검증을 함께 관리 | 앱에 필요한 설정을 명확히 적는다 |
| 오류 처리와 boundary | 장애를 진단하는 개발자와 사용자 | 렌더링 실패와 예상 오류의 처리 경로가 달랐음 | 오류를 handleError와 가까운 boundary로 연결 | 실패를 보여주고 분류할 경로를 정리한다 |
| shallow routing·refreshAll | 모달·목록 상태가 많은 앱의 개발자 | URL 변경과 데이터 갱신 때 화면 상태가 어긋남 | goto로 상태 전환, refreshAll로 갱신 | 상태 변경과 데이터 갱신을 구분한다 |
| service worker 모듈·타입 | 오프라인·캐시 경험을 만드는 팀 | worker 전용 import와 타입 준비가 번거로움 | 앱 모듈 재사용과 별도 tsconfig 제공 | 캐시 코드를 올바른 타입으로 다룬다 |
| sv migrate | 기존 SvelteKit 2 앱의 유지보수자 | 다수의 설정·API 변경을 수동으로 추적해야 함 | 안전하게 식별한 패턴은 자동 전환, 나머지는 표시 | 반복 수정을 줄이고 검토에 시간을 쓴다 |
2. 가치 기준별 핵심 변화
A. 설정과 타입: Kit와 도구가 같은 계약을 읽는다
SvelteKit 3에서는 svelte.config.js를 지원하지 않습니다.
설정은 vite.config.ts 등의 sveltekit(...) plugin 인자로 옮기며, 기존 kit 하위 옵션도 plugin의 최상위
옵션이 됩니다. 분산된 설정을 찾는 비용을 줄이는 변화지만 adapter와
preprocess 등 기존 설정이 빠지지 않았는지 검토해야 합니다.
$lib 자동 alias는 package.json의 imports에 선언하는 #lib로 바뀝니다. #lib/foo.ts처럼 확장자와 정확한 대상도 명시해야 합니다.
TypeScript 설정은 $app/tsconfig를 확장하고 include·exclude를 명시합니다. 단순 문자열
치환보다 테스트·편집기·빌드가 같은 경로를 해석하는지 확인하는 일이 중요합니다.
전환 규칙: 정식 마이그레이션 가이드 · 설계 배경: 8월 RC 안내
| 의존성 | 최소 버전 | 팀이 확인할 지점 |
|---|---|---|
| Node.js | 22.17 | 개발 머신·CI·실제 실행 환경을 함께 확인 |
| TypeScript | 6 | 새 타입 검사 결과와 도구 호환성 확인 |
| Svelte | 5.57.1 | Kit 버전과 Svelte 컴파일러 버전을 구분 |
| Vite | 8.0.12 | Vite 8이라고만 확인하지 말고 최소 patch도 확인 |
| @sveltejs/vite-plugin-svelte | 7 | Vite·Svelte와 맞는 plugin 조합 확인 |
위 최소 버전은 현재 정식 가이드 기준입니다. 개발 머신뿐 아니라 CI와 실제 배포 환경을 함께 맞춰야 합니다. Kit 3과 Svelte 3은 다른 제품 버전이며, 이번 Kit 릴리스는 Svelte 5를 요구합니다. 성능 개선 효과는 앱과 빌드 조건별로 측정해야 하며 고정 배속으로 해석하지 않습니다.
B. 환경 변수: 이름보다 선언과 공개 여부를 먼저 확인한다
src/env.ts에서 defineEnvVars로 필요한 변수를
선언하고, $app/env/private·$app/env/public으로
가져옵니다. 기본은 private·dynamic이며, public: true로
브라우저 공개를, static: true로 빌드 시점의 값 삽입을 선택합니다.
변수마다 필요한 범위와 해석 시점을 명시할 수 있습니다.
Standard Schema나 검증 함수로 값의 형식과 변환도 정의할 수 있으며,
유효하지 않은 값은 앱 시작이나 빌드를 실패시킵니다. 누락된 배포 설정을
뒤늦게 화면에서 발견하는 대신 설정 경계에서 확인할 수 있다는 것이 실무적
가치입니다. 공개 변수에 비밀값을 넣지 않는 책임은 여전히 팀에 있습니다.
기존 $env/*는 3에서 deprecated이며 즉시 제거된 것은 아닙니다.
선언·검증·해석 시점: 공식 환경 변수 문서
C. 오류 처리: 실패 화면과 로그의 기준을 함께 정리한다
handleError는 앱에서 의도한 오류, framework 오류, validation
오류, unknown 오류를 kind로 구분해 받습니다. 기존에
예상 오류를 별도 처리하던 코드와 로깅 정책을 함께 확인해야 합니다.
흔한 404까지 장애로 기록하면 로그 노이즈가 늘어날 수 있습니다.
렌더링 중 오류도 가까운 +error.svelte boundary로 전달되며,
더 작은 영역에는 svelte:boundary를 사용할 수 있습니다.
unknown 오류는 기본적으로 일반화된 메시지로 표시됩니다. hook에서 받은
원본 예외를 그대로 공개하면 비밀 정보가 노출될 수 있으므로, 사용자 설명과
내부 진단을 분리해야 합니다. 오류 경로가 정리되는 것이지 오류가 사라지는 것은 아닙니다.
오류 분류·표시·boundary: 공식 Errors 문서
D. 화면 상태: URL 변경과 데이터 갱신을 구분한다
| 작업 | 새 기준 | 사용자 흐름에서의 의미 |
|---|---|---|
| 얕은 상태 전환 | goto의 shallow: true | URL과 page.state를 바꾸되 전체 페이지 이동과 구분 |
| 새로고침 후 상태 | persistState: true | 설정한 page.state를 full reload 후 복원 |
| navigation hooks | shallow 전환에서도 호출 | 기존 hook이 전체 이동만 가정했다면 shallow 여부로 분기 |
| 데이터 재조회 | invalidateAll 대신 refreshAll | refreshAll은 page.state를 비우지 않음 |
모달이나 목록 선택처럼 페이지 전체를 이동하지 않는 상태도 navigation
hook과 연결됩니다. 기존 hook의 분석 이벤트·이탈 확인 등이 shallow 전환에
맞는지 점검해야 합니다. 상태 복원이 필요한 경우에만 persistState를 선택하고, 뒤로 가기·새로고침·데이터 재조회로
실제 사용자 흐름을 검증하는 것이 좋습니다.
상태 전환 옵션: 공식 navigation 문서 · 변경 비교: 마이그레이션 가이드
E. Service worker: 캐시 코드를 앱 모듈과 올바른 타입으로 다룬다
기존 $service-worker 대신 $app/env의 version, $app/manifest의 immutable·assets 등을 사용합니다. $app/service-worker의 self와 $app/tsconfig/service-worker를 확장하는 별도 설정으로
fetch event 타입을 맞춥니다. worker 코드는 루트 TypeScript 프로젝트에서
제외해야 하며, 등록 방식은 module입니다.
준비 코드와 타입 정합성이 개선되지만 자동으로 완성된 오프라인 앱이 되는 것은 아닙니다. 오래된 데이터의 허용 범위, 캐시 용량, 새 배포의 업데이트 시점을 설계해야 합니다. client-side navigation만 반복한다고 새 worker가 자동으로 발견되는 것도 아니므로, 운영 앱의 업데이트 경로를 별도로 시험해야 합니다.
모듈·타입·업데이트 조건: 공식 service worker 문서
F. 전환 운영: 자동 수정과 전환 완료를 구분한다
| 순서 | 할 일 | 완료 판단 기준 |
|---|---|---|
| 1 | 최근 2.x에서 경고 확인 | 3.0 전에 최신 2.x로 올려 targeted deprecation warnings 검토 |
| 2 | 환경과 변경 기준점 준비 | 최소 버전·adapter·관련 plugin 확인, 기존 변경은 먼저 안전하게 보존 |
| 3 | 마이그레이션 실행 | npx sv migrate sveltekit-3로 적용할 task 확인 |
| 4 | 수동 작업과 diff 검토 | @migration-task 검색, 생성·수정 파일과 API 동작 확인 |
| 5 | 운영 흐름 검증 | 타입·빌드뿐 아니라 오류 화면·로그인·폼·상태·캐시·배포 확인 |
정식 발표의 일괄 실행 예시는 npx sv migrate sveltekit-3 --tasks all --confirm입니다.
검토 단위를 작게 만들려면 적용 task를 나누되, 일부 task만 끝낸 상태가
작동 가능한 앱이라는 보장은 없습니다. 자동 도구는 안전하게 식별한 패턴만
바꾸므로 수동 작업 표시와 최종 diff를 확인해야 합니다. RC 시기의 sv@next 예시와 정식 명령도 구분합니다.
요청 경계도 변경됩니다. csrf.checkOrigin은 제거되고 csrf.trustedOrigins로 신뢰하는 origin을 지정합니다.
외부 URL로 redirect하려면 명시적으로 허용해야 합니다. 로그인·결제처럼
외부 서비스와 연결된 흐름은 신뢰 범위를 좁게 유지하며 다시 검증해야 합니다.
자동 마이그레이션의 가치는 검증을 없애는 데 있지 않고, 반복 수정을 줄여 동작 검토에 집중하게 하는 데 있습니다.
task와 수동 작업: 공식 sv migrate 문서 · 보안 변경: 정식 가이드
G. 아직 별개인 선택: remote functions는 실험 범위에 둔다
3.0 정식 발표는 remote functions가 아직 준비를 마치지 않았다고 명시합니다. 사용하는 데 필요한 Async Svelte도 experimental flag가 필요합니다. Kit 3 전환이 곧 remote functions의 안정화나 기존 load·actions의 전면 교체를 의미하지 않습니다. 기존 동작을 먼저 검증한 뒤 별도 실험으로 적용 범위를 평가하는 편이 변경 원인을 구분하기 쉽습니다.
정식과 실험 상태의 구분: 공식 출시 발표
3. 사용자 세그먼트별 해석
기존 앱 유지보수자
설정·import의 자동 수정 결과를 확인하고 오류·폼·navigation 회귀를 시험합니다. 새로운 통신 방식을 동시에 도입하기보다 기존 앱의 전환 완료를 먼저 판단합니다.
배포·운영 담당자
최소 버전과 adapter 조합을 CI·실행 환경까지 맞추고, 환경 변수 검증과 공개 범위를 확인합니다. unknown 오류는 안전하게 표시하고 routine 404 로깅을 구분합니다.
상태가 많은 제품의 개발자
모달·목록 선택·뒤로 가기·새로고침을 실제 흐름으로 확인합니다. shallow hook과 refreshAll은 상태 관리 정책을 명시할 기회이지 자동 동작 보증은 아닙니다.
오프라인 경험을 만드는 팀
worker 전용 타입과 모듈을 정리하고 오래된 캐시·새 배포·연결 끊김을 시험합니다. 캐시 전략과 업데이트 정책은 앱 요구에 맞춰 별도로 유지합니다.
4. 기능별 우선순위 평가
아래는 기존 운영 앱의 전환을 검토할 때 권장하는 순서이며, 공급자의 기능 순위는 아닙니다.
| 순서 | 점검 대상 | 이유 |
|---|---|---|
| 1 | 의존성·설정·import | 앱이 컴파일되고 CI와 배포에서 실행되기 위한 전환 기반 |
| 2 | 환경 변수·외부 요청 경계 | 배포 실패와 의도하지 않은 공개·신뢰 범위 변경을 먼저 점검 |
| 3 | 오류 처리 | 기존 로깅의 노이즈와 사용자에게 보여줄 오류 내용이 달라질 수 있음 |
| 4 | navigation·폼·상태 | 빌드가 통과해도 화면 이동과 데이터 갱신 경험은 회귀할 수 있음 |
| 5 | service worker | 사용 중인 앱에서는 오프라인·배포 업데이트 경로를 별도로 검증 |
| 6 | remote functions 검토 | Kit 3 정식 출시와 구분해 실험 범위에서 평가 |
5. 한 줄 포지셔닝
SvelteKit 3은 익숙한 앱의 설정·타입·실패 처리를 정리하는 정식 릴리스이며, 성공적인 전환의 기준은 자동 수정량이 아니라 배포와 사용자 흐름의 검증입니다.
기반을 맞춘다
Vite 설정, #lib import, 최소 의존성 버전을 함께 확인해 개발·CI·배포의 계약을 일치시킨다
경계를 드러낸다
환경 변수의 공개 범위, 오류의 표시·로깅, 외부 origin의 신뢰 범위를 명시한다
동작으로 검증한다
상태 전환·폼·캐시를 시험하고, remote functions는 정식 전환과 분리해 평가한다