목록으로
Web Framework 2026-10-01 정식 출시

SvelteKit 3 정식 출시: 설정 통합과 오류·환경 변수 개선

SvelteKit 3.0은 2026년 10월 1일 정식 출시됐습니다. 새로운 프레임워크로 다시 시작하기보다, 익숙한 앱 구조를 유지하며 설정·타입·오류 처리의 불일치를 줄이는 릴리스입니다. Vite 설정 통합과 표준 import, 명시적 환경 변수, 렌더링 오류 처리 개선을 기존 앱의 유지보수 관점에서 살펴봅니다.

10월 11일 기준 공식 발표와 현재 문서를 확인했습니다. 8월 Release Candidate 안내는 배경 설명으로만 참고하며, 설치 명령과 최소 버전은 정식 문서를 따릅니다. remote functions는 정식 출시 범위와 구분해야 합니다.

출처: SvelteKit 3 공식 출시 발표

이번 릴리스의 중심 메시지

앱을 새로 쓰기보다, 설정과 실패 경로를 명확히 해 계속 운영하기 쉬운 기반으로 옮깁니다.

이는 공식 변경을 묶은 이 글의 해석입니다. 마이그레이션 도구는 반복 수정을 줄이지만 동작 검증을 대신하지 않습니다. 새 실험 기능을 도입하는 결정도 별개입니다.

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.js22.17개발 머신·CI·실제 실행 환경을 함께 확인
TypeScript6새 타입 검사 결과와 도구 호환성 확인
Svelte5.57.1Kit 버전과 Svelte 컴파일러 버전을 구분
Vite8.0.12Vite 8이라고만 확인하지 말고 최소 patch도 확인
@sveltejs/vite-plugin-svelte7Vite·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: trueURL과 page.state를 바꾸되 전체 페이지 이동과 구분
새로고침 후 상태persistState: true설정한 page.state를 full reload 후 복원
navigation hooksshallow 전환에서도 호출기존 hook이 전체 이동만 가정했다면 shallow 여부로 분기
데이터 재조회invalidateAll 대신 refreshAllrefreshAll은 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오류 처리기존 로깅의 노이즈와 사용자에게 보여줄 오류 내용이 달라질 수 있음
4navigation·폼·상태빌드가 통과해도 화면 이동과 데이터 갱신 경험은 회귀할 수 있음
5service worker사용 중인 앱에서는 오프라인·배포 업데이트 경로를 별도로 검증
6remote functions 검토Kit 3 정식 출시와 구분해 실험 범위에서 평가

5. 한 줄 포지셔닝

SvelteKit 3은 익숙한 앱의 설정·타입·실패 처리를 정리하는 정식 릴리스이며, 성공적인 전환의 기준은 자동 수정량이 아니라 배포와 사용자 흐름의 검증입니다.

기반을 맞춘다

Vite 설정, #lib import, 최소 의존성 버전을 함께 확인해 개발·CI·배포의 계약을 일치시킨다

경계를 드러낸다

환경 변수의 공개 범위, 오류의 표시·로깅, 외부 origin의 신뢰 범위를 명시한다

동작으로 검증한다

상태 전환·폼·캐시를 시험하고, remote functions는 정식 전환과 분리해 평가한다