[SvelteKit] .svelte-kit 넌 누구니?

| 서론

SvelteKit 기반 Re:Log 프로젝트에서 실행했더니, '.svelte-kit'라는 폴더가 생겼는데요? 해당 폴더가 왜 생겼고, 무엇을 하는 것인지 정리한 내용을 공유해보려고 합니다.

| 왜 만들어진거지?

.svelte-kit 폴더는 SvelteKit이 빌드 또는 실행 중 자동으로 생성하는 ‘임시 컴파일 결과물’ 폴더입니다.

React로 비유하자면, node_modules/.vite나 Next.js의 .next 폴더와 비슷한 개념이죠.

하지만, 한 가지 중요한 차이점이 있습니다.

Svelte는 기존의 React나 Vue처럼 가상 DOM(Virtual DOM) 을 사용하는 프레임워크가 아닙니다.
React는 “렌더링 → 가상 DOM 비교 → 실제 DOM 반영”의 과정을 거쳐 화면을 업데이트하지만, Svelte는 그 모든 중간 단계를 생략합니다.

즉, 컴파일 시점에 이미 효율적인 자바스크립트 코드로 변환해, 실제 DOM을 직접 업데이트하도록 설계되어 있습니다.

-> 한마디로 “렌더링을 위한 계산”을 런타임이 아닌 빌드 단계에서 미리 처리해버리는 방식이에요.

이때, 그렇게 변환된 코드와 내부 실행 구조가 저장되는 공간이 바로 .svelte-kit 폴더입니다.

다시 말해, 이 폴더는 SvelteKit이 가상 DOM 없이도 빠르게 렌더링을 수행할 수 있게 하는 핵심 엔진이자,
프로젝트의 빌드 및 실행을 위한 중간 산출물 저장소인 셈입니다.

이 폴더는 npm run dev나 npm run build 명령어를 실행할 때 자동으로 생성되며,
수정할 필요는 없지만 내부 구조를 이해하면 SvelteKit의 작동 원리를 훨씬 명확히 파악할 수 있습니다.

| 어떤 역할을 할까?

.svelte-kit 폴더에는 다음과 같은 요소들이 자동으로 생성됩니다.

• 프로젝트 내 라우팅 구조(+page.svelte, +layout.svelte)를 분석해 클라이언트·서버용 코드로 변환된 결과 저장

• 각 페이지 이동, 매칭 규칙(matchers), SSR 처리 코드 등을 자동 생성

• 타입스크립트 환경을 위한 타입 정의($types.d.ts) 및 IntelliSense 제공

• SSR(서버 사이드 렌더링) 수행 시, 서버에서만 필요한 내부 로직을 분리 관리

즉, .svelte-kit은 라우트, 타입, SSR, 그리고 실행 로직이 연결되는 SvelteKit의 “작동 뇌” 역할을 담당하고 있습니다.

| 생성된 폴더 구조

.svelte-kit                              # SvelteKit이 자동 생성하는 빌드/개발용 폴더 (수정 X)
│
├── ambient.d.ts                         # 전역 타입 선언 ($app/navigation 등)
│
├── generated/                           # 라우트·클라이언트·서버 코드 자동 생성 결과
│   ├── client/                          # 브라우저 실행용 JS 코드
│   │   ├── app.js                       # 앱 초기화 및 라우팅 설정
│   │   ├── matchers.js                  # 라우트 매칭 규칙 (동적 경로 등)
│   │   └── nodes/                       # 각 페이지(+page.svelte)별 컴파일 결과
│   │       ├── 0.js                     # +layout.svelte 변환 결과
│   │       ├── 1.js                     # +page.svelte 변환 결과
│   │       └── 2.js                     # 다른 페이지(+page.svelte) 변환 결과
│   │
│   ├── root.js                          # 루트 엔트리 JS (앱 전체 구조)
│   ├── root.svelte                      # 루트 Svelte 컴포넌트 (전체 레이아웃 기반)
│   └── server/                          # SSR(서버 사이드 렌더링)용 코드
│       └── internal.js                  # 서버 렌더링 내부 로직
│
├── non-ambient.d.ts                     # 모듈별 타입 정의 (전역 제외)
├── tsconfig.json                        # 내부 타입스크립트 설정 파일
│
└── types/                               # 라우트 기반 타입 자동 생성
    ├── route_meta_data.json             # 모든 라우트 메타데이터 (loader 등)
    └── src/
        └── routes/
            └── $types.d.ts              # 각 라우트의 load(), PageData 타입 등

| 결론

결국 .svelte-kit 폴더는 SvelteKit이 프로젝트를 실행하기 위해 내부적으로 만들어내는 ‘작동 뇌 구조’ 같은 존재였습니다.

개발자가 직접 다룰 일은 거의 없지만, 이 폴더가 어떻게 생성되고 어떤 역할을 하는지를 이해하면 SvelteKit의 동작 원리(라우팅, 타입 생성, SSR 처리 등) 를 한눈에 파악할 수 있을 것 같았습니다.

특히, 타입 오류나 IntelliSense 꼬임 같은 문제가 발생했을 때 .svelte-kit 폴더를 삭제 후 npm run dev로 재생성하면 손쉽게 해결할 수 있다는 점도 기억하려고 합니다.