SvelteKit 시작하기

이 장에서는 SvelteKit 프로젝트를 만들고 개발 서버를 띄운 뒤, 첫 페이지를 고쳐 보는 데까지 진행합니다. 편집기 설정과 자주 쓰는 명령도 함께 정리합니다.

SvelteKit은 무엇인가

Svelte는 컴포넌트를 컴파일 단계에서 효율적인 자바스크립트로 바꾸는 UI 프레임워크이고, SvelteKit은 그 위에 라우팅, 서버 렌더링(SSR), 데이터 불러오기, 폼 처리, 빌드와 배포를 더한 애플리케이션 프레임워크입니다. 개발 서버와 번들링은 Vite가 맡고, SvelteKit은 Vite 플러그인 형태로 동작합니다. React에 Next.js가 있듯이 Svelte에는 SvelteKit이 있다고 생각하면 됩니다.

준비물

• 현재 LTS 판의 Node.js와 npm(또는 pnpm, Yarn, Bun)
• 편집기: Visual Studio Code와 공식 Svelte for VS Code 확장을 권장합니다
• 터미널 사용에 대한 기본 지식

설치된 Node.js 판은 다음처럼 확인합니다. SvelteKit이 요구하는 최소 판보다 낮다면 nodejs.org에서 LTS 판을 내려받습니다.

node --version
npm --version

프로젝트 만들기

SvelteKit 프로젝트는 공식 명령줄 도구 sv로 만듭니다. 따로 설치할 필요 없이 npx로 실행합니다.

npx sv create my-app
cd my-app
npm run dev

sv create를 실행하면 몇 가지를 묻습니다.

질문 없이 만들고 싶다면 옵션을 직접 넘깁니다. 이 안내서는 TypeScript를 기준으로 설명합니다.

npx sv create my-app --template minimal --types ts --no-add-ons --install npm

# 나중에 추가 기능을 붙일 때
npx sv add prettier eslint
npx sv add vitest playwright

개발 서버 실행

npm run dev는 Vite 개발 서버를 띄웁니다. 기본 주소는 http://localhost:5173이고, 파일을 저장하면 페이지 전체를 새로 고치지 않고 바뀐 부분만 반영되는 HMR이 동작합니다.

# 브라우저를 자동으로 열기
npm run dev -- --open

# 같은 네트워크의 다른 기기에서 접속하도록 열기
npm run dev -- --host

첫 페이지 고치기

src/routes/+page.svelte가 첫 화면(/)입니다. 내용을 다음처럼 바꾸고 저장해 보세요. $state는 Svelte 5의 룬(rune)으로, 값이 바뀌면 화면이 자동으로 갱신되는 반응형 상태를 만듭니다.

<script lang="ts">
  let name = $state('SvelteKit');
  let count = $state(0);
</script>

<h1>Hello, {name}!</h1>

<input bind:value={name} />
<button onclick={() => count++}>
  {count}번 눌렀습니다
</button>

bind:value는 입력 상자와 변수를 양방향으로 묶고, onclick은 일반 HTML 속성처럼 이벤트 처리기를 넘깁니다. 새 페이지를 만들려면 src/routes/about/+page.svelte처럼 폴더를 만들고 그 안에 +page.svelte를 두면 /about 주소가 생깁니다.

두 번째 페이지와 링크

src/routes/about/+page.svelte 파일을 만들고 다음 내용을 넣습니다. 첫 페이지에는 <a href="/about">소개</a> 링크를 추가합니다.

<svelte:head>
  <title>소개</title>
</svelte:head>

<h1>소개</h1>
<p>이 페이지의 주소는 /about 입니다.</p>
<a href="/">처음으로</a>

<svelte:head> 안의 요소는 문서의 <head>에 들어가므로 페이지마다 제목과 메타 태그를 정할 수 있습니다. 링크를 누르면 SvelteKit이 페이지 전체를 다시 받지 않고 필요한 코드만 불러와 화면을 바꿉니다. 첫 요청은 서버에서 HTML로 렌더링되므로 검색 엔진도 내용을 읽을 수 있습니다.

자주 쓰는 명령

package.json의 scripts에는 다음 명령이 들어 있습니다.

편집기 설정

VS Code에서는 Svelte for VS Code 확장을 설치하면 .svelte 파일의 문법 강조, 자동 완성, 타입 오류 표시, 서식 정리를 쓸 수 있습니다. 같은 언어 서버를 쓰는 확장이 다른 편집기(JetBrains, Neovim, Zed 등)에도 있습니다. 커밋 전에는 npm run check로 프로젝트 전체를 한 번 더 검사하는 습관을 들이면 좋습니다.

정리

• SvelteKit은 Svelte 컴포넌트 위에 라우팅, SSR, 데이터 불러오기, 배포를 더한 Vite 기반 프레임워크입니다.
• npx sv create로 프로젝트를 만들고 npm run dev로 개발 서버를 띄웁니다.
• 페이지는 src/routes 안의 +page.svelte 파일이며, 폴더 구조가 곧 주소입니다.
• 추가 기능은 npx sv add로 나중에도 붙일 수 있습니다.