스벨트킷 3 정식 출시, 바뀐 설정 5가지와 옮기는 명령

발행 2026.10.02읽는 시간 약 16분

2026년 10월 1일, 스벨트 개발팀이 정식 버전인 스벨트킷 3(SvelteKit 3.0)을 공개했습니다. 기존 프로젝트에서는 설정 파일의 위치와 $lib 별칭이 가장 먼저 달라지며, 이전 작업의 대부분은 명령 하나로 처리됩니다.

스벨트킷 3에서 바뀐 것 다섯 가지

설정은 이제 vite.config 에서 다루고, 별칭은 $lib 가 아니라 #lib 를 씁니다.

공식 블로그에서 소개한 변경점은 모두 다섯 갈래입니다. 설정 파일에서 시작해 별칭, 환경변수, 서비스 워커를 거쳐 오류 처리까지 이어지는 차례로 정리되어 있습니다.

별칭이란 긴 경로에 붙이는 짧은 이름을 뜻합니다. 이번에 바뀐 까닭은 표준을 따르기 위해서이며, #lib 는 Node 가 정한 서브패스 임포트 방식이어서 Vite 와 타입스크립트가 별도 변환 없이 인식합니다.

다만 손볼 부분이 하나 늘었습니다. #lib/foo.js 처럼 경로 끝에 확장자까지 적어야 합니다.

변경점이 이것뿐인 것은 아닙니다. 변경 기록인 CHANGELOG 의 3.0.0 항목을 열어 보면 breaking 이 붙은 줄만 70개가 넘게 나옵니다.

원문 읽기: Svelte 블로그 · SvelteKit 3 is here

누가 영향을 받나요?

스벨트킷 2 로 만든 프로젝트라면 예외 없이 대상이며, 제일 먼저 확인할 부분은 요구 최소 버전입니다.

3.0 부터는 Vite 8 을 비롯해 함께 쓰는 도구들의 최소 요구 버전이 한꺼번에 높아졌습니다.

버전만 올리면 마무리되는 프로젝트도 있습니다. 하지만 아래 항목에 걸리면 코드 수정이 필요합니다.

• $app/stores 를 사용하는 코드 — 해당 모듈이 제거되어 $app/state 로 교체해야 합니다.
• adapter-vercel 을 edge 런타임으로 돌리는 방식은 지원이 끝났습니다.
• ORIGIN 환경변수는 adapter-node 에서 삭제됐고, 같은 역할은 paths.origin 설정이 맡습니다.
• env 같은 값은 이제 cloudflare:workers 에서 가져오며, 예전에 adapter-cloudflare 가 platform 으로 건네던 방식은 쓰지 않습니다.
• 한글처럼 ASCII 범위를 벗어난 쿠키 이름 — cookie v2 부터는 받아들여지지 않습니다.

대상이 아닌 경우도 명확합니다. 스벨트킷을 쓰지 않고 스벨트만 사용하는 프로젝트는 이번 릴리스와 관계가 없습니다.

원문 읽기: SvelteKit Docs · Migrating to SvelteKit v3

대상인지 확인을 마쳤으니 이제 명령을 실행해 볼 차례입니다.

새 프로젝트 만들기와 기존 프로젝트 옮기기

처음 만드는 경우에는 npx sv create 를, 이미 있는 프로젝트를 옮기는 경우에는 npx sv migrate sveltekit-3 을 실행합니다.

공식 문서가 안내하는 기본 명령은 npx sv create my-app 한 줄이며, 실행하면 타입스크립트처럼 함께 쓸 도구를 선택하라는 질문이 나옵니다. 아래 순서는 질문 단계를 생략하고 최소 템플릿으로 프로젝트를 만든 다음 빌드까지 진행한 기록입니다.

npx sv create my-app --template minimal --types ts --no-add-ons --no-install
cd my-app
npm install
npm ls --depth=0
npm run build

직접 실행함 (환경: Windows 10 · Node 22.22.0) · 생성, 설치, 버전 조회, 운영용 빌드를 차례로 실행 · 설치 줄은 이 PC 에서 옵션을 붙여 실행(아래 상자)

+-- @sveltejs/adapter-auto@8.0.0
+-- @sveltejs/kit@3.0.0
+-- @sveltejs/vite-plugin-svelte@7.3.1
+-- svelte-check@4.7.6
+-- svelte@5.57.1
+-- typescript@6.0.3
`-- vite@8.3.2

vite v8.3.2 building ssr environment for production...
✓ built in 2.20s
vite v8.3.2 building client environment for production...
✓ built in 2.30s
> Using @sveltejs/adapter-auto
✔ done

직접 실행함 (환경: Windows 10 · Node 22.22.0) · 앞 명령의 출력 중 버전 목록과 빌드 결과만 추려 실음

폴더 안에서 svelte.config.js 는 보이지 않았고, 어댑터는 vite.config.ts 쪽에 설정돼 있었습니다. package.json 을 열면 imports 필드에 #lib 가 선언돼 있었습니다.

블로그 글은 명령 끝에 --tasks all --confirm 을 붙여 모든 작업을 단번에 돌리는 형태로 소개했습니다. 가이드에 실린 기본형은 아래 한 줄입니다.

npx sv migrate sveltekit-3

공식 문서 예시 · 스벨트킷 2 에서 3 으로 이전하는 명령 (스벨트킷 마이그레이션 가이드)

문서에서 권하는 진행 순서는 다음과 같습니다.

1. 먼저 스벨트킷 2 의 마지막 버전까지 올려서 폐기 예정 경고를 확인합니다.
2. 진행 중인 작업을 커밋합니다. 작업 트리가 정리되지 않은 상태라면 명령이 먼저 확인 질문을 합니다.
3. 마이그레이션 명령을 실행한 뒤 생성된 diff 를 살펴봅니다.
4. 의존성을 설치하고, 이어서 타입 검사와 빌드를 수행합니다.

스벨트킷 2 형태로 만든 최소 예제에 이 명령을 적용하자 12개의 작업이 순서대로 실행됐습니다. 라우트 파일이 달라진 부분은 아래와 같습니다.

-  import { page } from '$app/stores';
-  import { base } from '$app/paths';
-  import { greet } from '$lib/greet';
+  import { resolve } from '$app/paths';
+  import { page } from '$app/state';
+  import { greet } from '#lib/greet.js';

-<p>{greet('kit')} — {$page.url.pathname}</p>
+<p>{greet('kit')} — {page.url.pathname}</p>

직접 실행함 (환경: Windows 10 · Node 22.22.0) · src/routes/+page.svelte 의 diff 일부. 앞 명령에 –tasks all 과 –confirm 을 얹고 –no-install, –no-git-check 까지 붙여 돌린 결과

같은 실행 뒤에는 svelte.config.js 가 사라졌고, 어댑터 설정이 vite.config.js 로 자리를 옮겼습니다. tsconfig.json 에서는 extends 가, package.json 에서는 버전 범위가 함께 바뀌었습니다.

확인한 것은 파일이 바뀌는 과정까지입니다. 의존성 설치와 빌드는 실행하지 않았습니다.

원문 읽기: SvelteKit Docs · Creating a project

옮길 때 걸리는 것과 되돌리는 법

자동 변환이 닿지 않은 부분은 @migration-task 주석과 MIGRATION_TASKS.md 에 기록됩니다.

이 명령은 안전하게 식별되는 패턴만 변환합니다. 그 외에는 직접 손봐야 하며, 이미 삭제된 것과 앞으로 삭제될 것으로 나누면 아래 표와 같습니다.

이름은 같지만 동작이 달라진 항목도 있습니다.

• 쿠키를 만들 때 path 를 지정하지 않으면 기본값은 '/' 입니다.
• 외부 주소로 redirect 를 보내려면 external 옵션을 함께 넘겨야 합니다.
• 폼 액션의 응답에는 fail() 에 전달한 상태 코드가 그대로 사용됩니다.
• 위치와 상관없이 이름이 server 인 폴더는 서버에서만 쓰이는 코드로 취급됩니다.

문서에는 이전을 취소하는 전용 명령이 없습니다. 대신 실행 전에 커밋해 두고, 작업을 하나씩 실행하면서 매번 커밋하도록 안내합니다.

아직 확정되지 않은 사항도 하나 남았습니다. 리모트 함수는 서버 함수를 클라이언트에서 타입 정보 그대로 호출하는 기능인데, 실험 플래그를 켜야 쓸 수 있고 정식 전환 일정은 공개되지 않았습니다.

원문 읽기: Svelte CLI Docs · sv migrate

올리기 전에 볼 체크리스트

Node 가 22.17 이상인지, 어댑터도 함께 올렸는지를 가장 먼저 점검합니다.

어댑터 역시 같은 날 새 메이저 버전이 공개됐습니다. 공식 어댑터는 모두 스벨트킷 3 을 필요로 합니다.

• node -v 의 결과가 22.17 이상이다 · 마이그레이션 가이드
• 2.70.3 으로 올린 스벨트킷 2 에서 폐기 경고를 확인했다 · 마이그레이션 가이드 · npm
• 명령을 돌리기 전에 현재 상태를 커밋해 두었다 · sv migrate 문서
• 어댑터는 node 용 6, vercel 용 7, cloudflare 용 8 로 올렸다 · GitHub 릴리스
• @migration-task 를 검색했을 때 결과가 0건이다 · sv migrate 문서
• MIGRATION_TASKS.md 에 적힌 일을 모두 마치고 해당 파일을 삭제했다 · 생성된 파일의 안내
• 타입 검사와 빌드가 오류 없이 끝난다 · sv migrate 문서

일곱 항목이 모두 체크되면 업그레이드할 준비가 끝난 것입니다.

원문 읽기: GitHub sveltejs/kit · @sveltejs/kit@3.0.0 릴리스

스벨트킷 3, 자주 묻는 질문

Q. $lib를 그대로 두면 어떻게 되나요?
A. 스벨트킷 3 에서는 $lib 가 저절로 생기지 않습니다. 대신 imports 항목(package.json)에 #lib 를 적고 소스의 경로를 고치면 되며, 마이그레이션 명령의 lib-alias 작업이 이 과정을 맡습니다.

Q. $env 모듈은 바로 못 쓰나요?
A. 여전히 쓸 수 있습니다. 변경 기록에 따르면 $app/environment 와 $env/… 는 폐기 예정으로 분류된 별칭이며, 새 코드에는 $app/env 계열을 쓰라는 것이 공식 안내입니다.

Q. 설정을 옮기면 svelte.config.js는 지워도 되나요?
A. 네, 삭제해도 됩니다. 가이드는 이 파일의 지원이 끝났다고 설명하고, 과거 config.kit 밑에 있던 설정값은 sveltekit() 플러그인에 최상위 옵션으로 전달하게 됐다고 합니다.

변경된 항목이 많은 것에 비해 이전 명령 자체는 간단합니다. 앞으로 리모트 함수가 언제 정식으로 전환될지가 가장 관심이 가는 대목입니다.

스벨트킷 3 관련해 더 궁금한 점이 있으신가요? 댓글로 알려주세요.