cachesdev/svelte-deep-knowledge

Svelte 심층 지식

이 문서를 잠재적인 지식 격차의 인덱스로 사용하세요. 계획 및 구현 중에 공식 Svelte MCP를 통해 관련 API를 확인하세요.

2026-11-01, Svelte 5.57.3, SvelteKit 3.1.1, SvelteKit 2.70.3 기준으로 검증됨.

설치된 버전부터 시작하세요

1. 패키지 버전과 Vite 구성을 확인합니다. 설치된 Kit 메이저 버전과 활성화된 실험적 플래그에 맞게 지침을 조정합니다.
2. Svelte MCP의 list-sections를 호출한 다음, get-documentation을 통해 관련 섹션을 가져옵니다. MCP와 svelte.dev는 Kit 3 문서를 제공합니다. Kit 2 프로젝트의 경우 sveltejs/kit 저장소의 version-2 브랜치에 있는 documentation/docs에서 해당 페이지를 읽습니다.
3. Kit 3 프로젝트 및 Kit 2 → 3 마이그레이션의 경우 Kit 3 참조를 읽으세요. Kit 2 프로젝트의 경우 Kit 2 참조를 읽으세요.
4. 새로 생성하거나 편집한 Svelte 컴포넌트/모듈에 대해 svelte-autofixer를 실행하고 해당되는 결과를 해결합니다. 통합 및 타입 검사에는 프로젝트의 검사 도구를 사용하세요.

새로운 Svelte API, 비동기 렌더링, 첨부 파일 및 컴파일러 도구의 예는 Svelte 참조를 읽으세요.

원격 함수, 경계 및 await

실험적 async를 채택하는 새로운 SvelteKit 앱의 경우, 컴포넌트 데이터에는 직접 await와 함께 원격 함수를 선호하고, 로딩/에러 UI에는 세분화된 경계를 사용하세요. 서버에서 렌더링되어야 하는 항목에 따라 svelte:boundary 배치를 선택합니다.

• experimental.remoteFunctions와 compilerOptions.experimental.async를 함께 활성화합니다. 공식 원격 함수 설정에는 두 플래그가 모두 필요합니다.
• load, 폼 액션, +server 라우트는 계속 지원되지만 권장되지 않습니다. 작업에 마이그레이션이 포함되지 않는 한 기존 아키텍처를 따르세요.
• .loading, .error, .current는 계속 지원되는 쿼리 API입니다. 직접 await가 선호되는 메커니즘입니다.
• 렌더링 및 명령형 컨텍스트에서 await query(args)를 사용합니다.
• {#await}는 계속 지원되지만 권장되지 않으며, 자체적인 프로미스 상태 동작이 있습니다. 조정된 비동기 렌더링을 위해 직접 await와 경계를 사용하고, {#await}의 동작이 작업에 적합한 경우에는 유지합니다.

MCP 섹션 kit/remote-functions, svelte/await-expressions, svelte/svelte-boundary를 확인하세요.

비동기 렌더링 동작

• 컴포넌트 수준의 await는 Svelte 5.36에서 도입되었으며, 비동기 SSR은 5.39에서 도입되었습니다. Await는 최상위 스크립트, $derived, 마크업에서 지원됩니다.
• Svelte는 비동기 작업이 해결되는 동안 종속된 UI 업데이트를 조정합니다. 독립적인 템플릿 await 표현식은 동시에 실행됩니다. 순차적인 스크립트 await는 여전히 워터폴을 생성합니다. 결과를 기다리기 전에 독립적인 작업을 시작하세요.
• 경계의 pending 스니펫은 초기 생성 시 나타납니다. 해당 경계에서 후속 작업을 위해 $effect.pending()를 사용하세요. 그 수는 하위 경계를 제외합니다.
• SSR 중에 pending이 있는 경계는 플레이스홀더를 렌더링하고 해당 콘텐츠를 건너<0xEB9B>니다. 이러한 경계 외부의 await 표현식은 await render(...)가 완료되기 전에 해결됩니다. 초기 HTML에 필요한 콘텐츠를 그에 따라 배치하세요. 이 API는 아직 스트리밍 SSR을 제공하지 않습니다.
• 5.41에 추가된 $state.eager(value)는 조정된 업데이트가 기다리는 동안 즉각적인 피드백을 노출합니다. 활성 탐색 표시기와 같은 사용자 피드백에 사용합니다.
• tick()은 보류 중인 상태 변경을 기다리고, 5.36에 추가된 settled()는 이로 인해 발생하는 비동기 작업과 결과 DOM 업데이트도 기다립니다.

에러 경계

• <svelte:boundary>는 렌더링/이펙트 실패를 위해 failed(error, reset) 및 onerror(error, reset)를 지원합니다. 이벤트 핸들러 및 분리된 비동기 오류는 해당 호출 사이트에서 처리합니다.
• failed 스니펫은 Svelte 5.53부터 SSR 중 발생한 오류도 포착합니다. SvelteKit에서는 오류가 먼저 handleError를 거치므로 스니펫은 정리된 App.Error를 받습니다. onerror는 실패한 경계가 하이드레이션될 때 실행됩니다.
• Kit 3은 렌더링 오류를 handleError를 통해 가장 가까운 +error.svelte로 보내며, 이 컴포넌트가 경계 역할을 합니다. 비동기 클라이언트 handleError는 compilerOptions.experimental.async가 필요합니다. Kit 2.54+는 동일한 통합을 위해 experimental.handleRenderingErrors가 필요합니다.
• 경계 문서의 이전 "5.51부터"라는 메모는 게시된 변경 로그와 충돌합니다. 도입 버전으로 5.53을 사용하고 SSR/하이드레이션 문제를 진단할 때 현재 패치를 확인하세요.

템플릿 기능

선언 태그, Svelte 5.56+

• 마크업-로컬 변수에는 {let ...} 및 {const ...}를 선호합니다. {@const}는 레거시로 문서화되어 있으며 이전 프로젝트에서 계속 사용할 수 있습니다.
• 일반 선언은 값을 초기화합니다. 반응성을 위해 명시적인 런을 사용하세요: {let count = $state(0)}, {const doubled = $derived(count * 2)}.
• 반응형 {@const area = width * height}를 마이그레이션하려면 {const area = $derived(width * height)}가 필요합니다. 일반 {const area = width * height}는 반응형이 아닙니다.
• 선언은 요소/블록 내에서 렉시컬 스코프를 사용하고, 외부 변수를 섀도잉할 수 있으며, 사용보다 먼저 나타나야 합니다. 여러 선언자가 지원됩니다.

첨부 (Attachments)

• Svelte 5.29+에서 새로운 요소 통합을 위해 {@attach ...}를 선호합니다. 첨부에서 정리(cleanup)를 반환합니다.
• 첨부는 반응형 읽기를 추적하고 종속성이 변경되면 다시 실행됩니다. Falsy 값은 첨부를 비활성화합니다. 하위 효과 내부의 getter를 통해 변경되는 옵션을 읽음으로써 값비싼 설정을 반복하지 않도록 합니다.
• 컴포넌트 래퍼는 첨부를 보유한 props를 의도된 요소로 전달해야 합니다. createAttachmentKey()는 스프레드 객체에서 첨부를 지원합니다.
• fromAction(action, () => argument)는 기존 액션의 동작을 유지합니다. 두 번째 인수는 getter입니다. 이 헬퍼는 첨부 자체 이후인 5.32에 도입되었습니다.

클래스, 바인딩 및 HTML

• class는 5.16부터 중첩된 배열과 객체를 허용합니다. svelte/elements의 ClassValue는 5.19부터 래퍼 props에 사용할 수 있습니다.
• 함수 바인딩은 5.9부터 bind:value={get, set}를 사용합니다. 읽기 전용 바인딩의 경우 getter에 null을 사용합니다.
• 숫자 입력은 비어 있거나 유효하지 않을 때 undefined를 생성할 수 있습니다. 체크박스 상태는 bind:checked 및 bind:indeterminate를 사용할 수 있고, 라디오 그룹은 bind:group을 사용합니다.
• 입력은 5.6부터 defaultValue/defaultChecked를 지원합니다. 셀렉트는 5.57부터 defaultValue를 지원하며, 폼 리셋 동작을 포함합니다. 기본값을 제공할 때 바인딩 우선 순위를 확인하세요.
• 사용자 정의 가능한 네이티브 셀렉트는 5.47부터 지원됩니다. 사용자 정의 셀렉트 위젯을 교체하기 전에 브라우저 지원과 문서화된 <selectedcontent> 패턴을 확인하세요.
• JavaScript 스타일 주석은 5.53부터 속성 사이에서 유효합니다: <div /* 설명 */ class="card">.
• {@html}은 5.52부터 TrustedHTML을 허용합니다. Trusted Types 지원은 임의의 입력을 삭제(sanitize)하지 않습니다. 신뢰할 수 있는 소스 또는 삭제 정책을 사용하세요.

각 블록과 스니펫

• {#each items as { id, name }}는 항목을 구조 분해합니다. 범위 반복은 {#each { length: 8 }, index}를 사용할 수 있습니다.
• 정체성이 중요한 목록에는 안정적인 항목 키를 선호합니다. 항목을 편집할 때는 항목 객체를 통해 해당 속성을 바인딩하여 변이가 소스에 도달하도록 합니다.
• 스니펫은 마크업에서 선언되고 {@render snippet(...)}로 렌더링됩니다. 최상위 스니펫은 인스턴스 상태를 캡처하지 않는 경우 5.5부터 <script module>에서 내보낼 수 있습니다.
• 스니펫은 5.30부터 제네릭을 지원합니다. 컴포넌트 제네릭은 <script lang="ts" generics="T">를 사용합니다.
• 런 모드에서는 컴포넌트 변수가 <Component />로 동적으로 렌더링됩니다. 재귀적 컴포넌트는 자신을 가져올 수 있습니다.

런과 공유 상태

상태와 Props

• $state.raw는 깊은 프록시 없이 재할당을 추적합니다. 전체를 교체하는 큰 값에 사용합니다. $state.snapshot은 일반 데이터를 추출하고 toJSON()을 존중합니다.
• 클래스 인스턴스는 깊게 프록시되지 않습니다. $state 필드를 사용하거나, 5.31부터는 첫 번째 생성자 할당을 사용하세요. 반응형 필드는 열거 불가능한 접근자가 됩니다. 메서드를 콜백으로 전달할 때 this를 유지합니다.
• 반응형 값을 함수에 전달하면 현재 값을 전달합니다. 함수가 미래 값이 필요할 때는 getter를 전달합니다. 프록시를 구조 분해하면 현재 값도 읽습니다.
• 공유 런 로직에는 .svelte.js/.svelte.ts를 사용합니다. 소비자가 변경되는 상태를 필요로 할 때는 안정적인 상태 객체 또는 접근자를 내보내고, 재할당된 런 상태를 직접 내보내는 것은 제한됩니다.
• SSR 중에는 컴포넌트 컨텍스트를 통해 사용자별 상태의 범위를 지정합니다. 공유 모듈 상태는 요청 간에 누출될 수 있습니다.
• 5.20에 추가된 $props.id()는 SSR과 하이드레이션 간에 일치하는 컴포넌트 인스턴스 ID를 제공합니다.
• $bindable()은 바인딩 가능한 prop을 선언합니다. Props는 로컬에서 재할당될 수 있습니다. 부모의 바인딩 불가능한 프록시를 변이하면 소유권 경고가 발생합니다. 폴백 값은 자동으로 프록시되지 않습니다.
• $state<T>()의 실제 초기화되지 않은 타입(undefined 포함)을 유지하거나 유효한 초기값을 제공합니다. 액세스 사이트에서 좁히기를 사용합니다.

파생(Derived)과 이펙트

• 계산된 값에는 $derived(expression) 또는 $derived.by(fn)를 사용합니다. let으로 선언된 Derived는 5.25부터 낙관적 UI를 위해 재할당될 수 있습니다. 종속성 변경 시 다시 계산됩니다.
• 구조 분해된 $derived 값은 반응성을 유지합니다. 반환된 객체는 자동으로 깊은 프록시가 아닙니다. 참조 동등성은 다운스트림 작업을 건너뛸 수 있습니다.
• 이펙트는 최신 실행의 동기적 읽기를 추적합니다. await 이후 일반 비동기 콜백 내부의 읽기는 자동으로 종속성이 아닙니다.
• $effect는 브라우저에서 실행됩니다. 정리(cleanup)를 동기적으로 반환합니다. 외부 동기화를 위해 이펙트를 예약하고 사용자 트리거 작업은 핸들러에 넣습니다.
• $effect.tracking()은 추적 컨텍스트를 감지합니다. $effect.root()는 수동으로 관리되는 범위를 만들고 disposer를 반환합니다.
• 5.35에 추가된 getAbortSignal()은 이펙트 또는 derived 내부에서 실행되어야 합니다. 시그널은 재실행 또는 파괴 시 중단됩니다. 해당 반응형 계산이 소유한 fetch 작업에 사용합니다.
• untrack(fn)은 종속성 추적에서 읽기를 제외합니다.
• $inspect(...).with(fn)은 "init"/"update" 다음에 값을 받습니다. 5.14에 추가된 $inspect.trace(label?)는 추적된 함수의 첫 번째 문장이어야 합니다.
• $host()는 사용자 정의 요소를 위한 것이며 호스트 DOM 요소를 반환합니다.

런타임 모듈

• createContext<T>()는 5.40부터 타입이 지정된 컨텍스트를 제공합니다. 5.57부터 [get, set, has]를 반환합니다. has()는 get() 전에 가용성을 확인하며, 설정되지 않은 경우 get()은 예외를 발생시킵니다. 컨텍스트 조회는 현재 컴포넌트와 조상을 포함합니다. 초기화 중에 컨텍스트 접근자를 호출하고, 스크립트의 첫 번째 await 전에 컨텍스트를 설정합니다. 5.57.1부터 SSR 중에 setContext를 늦게 호출하면 set_context_after_init가 발생합니다.
• svelte/reactivity는 SvelteMap, SvelteSet, SvelteDate, SvelteURL, SvelteURLSearchParams를 제공합니다. Map/Set 항목은 깊은 반응형으로 만들어지지 않습니다.
• Svelte 5.57은 SvelteMap.getOrInsert(key, value) 및 getOrInsertComputed(key, key => value)를 추가합니다. 계산된 콜백은 키가 없을 때 실행되며, 기존 undefined 항목의 올바른 처리를 포함합니다.
• MediaQuery와 createSubscriber는 5.7에 도입되었습니다. createSubscriber를 사용하여 외부 이벤트를 공유 구독 설정 및 정리를 통해 추적된 읽기에 연결합니다. MediaQuery는 SSR 폴백을 허용합니다. 동일한 동작을 표현할 수 있는 경우 CSS를 사용합니다.
• svelte/reactivity/window는 5.11부터 치수, 스크롤 위치, 온라인 상태, 화면 위치, 픽셀 비율에 대한 반응형 .current 값을 제공합니다. SSR 중에는 사용할 수 없는 window 값을 고려하세요.
• svelte/events의 on()은 선언적 이벤트 핸들러와의 순서를 유지하고 정리를 반환합니다. 선언적 전역 리스너에는 <svelte:window>/<svelte:document>를 사용합니다.
• flushSync(fn?)는 보류 중인 업데이트를 동기적으로 플러시합니다. createRawSnippet는 설정/정리를 사용한 프로그래매틱 마크업을 지원합니다. getAllContexts()는 프로그래매틱 마운팅을 위한 현재 컨텍스트 맵을 제공합니다. 초기화 중에 호출합니다.
• svelte/motion의 Spring과 Tween은 5.8부터 더 이상 사용되지 않는 spring()/tweened() 스토어를 대체합니다. 둘 다 .target, .current, .set(), .of(fn)을 노출합니다. Spring.set은 preserveMomentum을 지원하고, prefersReducedMotion은 접근 가능한 모션을 지원합니다.
• 5.55부터 모션 내보내기에는 TweenOptions, SpringOptions, SpringUpdateOptions, Updater가 포함됩니다.
• 5.44에 추가된 hydratable(key, fn)는 하이드레이션 중 재사용을 위해 데이터를 직렬화합니다. devalue를 사용하며 중첩된 프로미스를 지원합니다. 네임스페이스 키는 충돌을 방지합니다. Kit 원격 함수는 이미 이 계층을 처리합니다.
• CSP를 사용하는 경우, 사용자 정의 SSR 통합은 응답별 nonce 또는 정적 해시로 render를 구성하고 일치하는 값을 응답 헤더에 넣어야 합니다. Svelte 5.46은 렌더 CSP 지원을 추가했습니다. 5.57은 svelte/server에서 RenderOutput, SyncRenderOutput, Csp, Sha256Source를 내보냅니다.
• 도구의 경우, print()는 5.45부터 최신 Svelte AST를 소스로 변환하고, parseCss()는 5.48에 도입되었습니다. 컴파일러 옵션 css, runes, customElement는 5.54부터 파일 이름에 의존하는 함수가 될 수 있습니다. 이러한 API를 사용하기 전에 Svelte 참조를 읽으세요.

SvelteKit

새로운 앱은 Kit 3 (npx sv create)을 사용합니다. Kit 2 앱을 마이그레이션하려면 npx sv migrate sveltekit-3을 실행한 다음 생성된 TODO를 처리하세요. Kit 2 지침은 2.x에 남아 있는 프로젝트에만 적용됩니다.

Kit 3 기준

• Kit 3은 Node 22.17, TypeScript 6, Svelte 5.57.1, Vite 8.0.12, vite-plugin-svelte 7이 필요합니다.
• 구성은 vite.config.ts 내부의 sveltekit({...})에 있으며, Kit 옵션은 compilerOptions 옆 최상위 수준에 있습니다. Kit 3은 더 이상 svelte.config.js를 읽지 않습니다.
• #lib는 package.json 하위 경로 가져오기를 통해 $lib를 대체합니다. #lib/server/db.ts와 같이 파일 확장자를 작성합니다.
• server 파일 이름 세그먼트 또는 src/routes 외부의 server 디렉토리는 모듈을 서버 전용으로 표시합니다. data.remote.ts 또는 remote.ts와 같은 remote 파일 이름 세그먼트는 원격 모듈을 표시합니다.
• @sveltejs/kit/env의 defineEnvVars를 사용하여 src/env.ts에서 환경 변수를 선언합니다. $app/env/private 및 $app/env/public에서 값을 가져오고, browser, building, dev, version은 $app/env에서 가져옵니다. 공개 변수는 %sveltekit.env.NAME%으로 app.html에 나타날 수 있습니다. $env/* 및 $app/environment는 더 이상 사용되지 않는 별칭입니다.
• $app/stores는 제거되었습니다. $app/state를 사용하세요. page.url은 읽기 전용입니다. `new URL".

...(이후 내용은 원문이 잘려서 번역할 수 없지만, 전체 SKILL.md를 위와 같은 형식으로 번역합니다.)