초보를 위한 스벨트킷의 파일 기반 라우팅 시스템 설명

2026.07.07 - [Svelte_SvelteKit] - 초보를 위한 스벨트킷 프로젝트의 폴더 구조 설명

초보를 위한 스벨트킷 프로젝트의 폴더 구조 설명

 

앞서 스벨트킷으로 프로젝트를 생성했을 때 폴더구조에 대해 살펴보았습니다.

여기서 파일 기반 라우팅이라는 얘기가 나오는데 좀 더 구체적으로 알아보겠습니다.

 

---

먼저 페이지 라우팅이라는 것은 사용자가 브라우저에 URL을 입력하거나 클릭했을 때 그 경로를 찾아가 보여주는 것입니다.

기존처럼 링크를 클릭했하면 해당 페이지를 서버에서 만들어서 보내주는 방식을 서버 사이드 라우팅(SSR: Server Side Routing)라고 하며 최근의 리액트 등에서 사용하는 방식은 클라이언트 사이드 라우팅(CSR: Client Side Routing)이라고 해서 처음 접속할 때 필요한 자바스크립트를 모두 받아두고 링크를 클릭하면 해당하는 부분의 UI만 갈아끼우는 방식입니다.

 

이렇게 하면 불필요한 상단, 하단을 다시 불러온다거나 해서 화면이 깜빡일 필요없이 부품 갈아끼우듯 자연스럽고 빠르게 화면에 보여줍니다.

 

스벨트킷에서는 이런 페이지 라우팅 방식을 파일 기반으로 해서 about이라는 폴더를 만들면 그게 바로 URL이 되고, 그 안의 +page.svelte 파일을 불러오게 됩니다.

 

그럼 이런 의문이 들 수 있습니다.

페이지마다 반복되는 상단, 하단 또는 사이드바는 어떻게 처리하지?

 

아래 이미지의 우측 설명에서 보듯이 +layout.svelte 라는 전체 레이아웃을 정하는 페이지가 있고 이 곳에서 상단, 하단, 본문 등을 정의하고 /about 이란 URL로 이동했을 때 본문 영역에만 해당 UI 부분을 교체해서 보여주게 됩니다.

 

 

---

 

 

스벨트킷(SvelteKit)의 파일 기반 라우팅 시스템(Filesystem-based Router)은 코드베이스의 폴더와 파일 구조가 그대로 웹사이트의 URL 주소로 매핑되는 구조를 가집니다. 복잡한 설정 없이 직관적인 규약을 따라 작동하며, 구체적인 작동 방식은 다음과 같습니다.

 

---

1. 라우트 경로를 결정하는 폴더 구조

스벨트킷은 src/routes 폴더를 기준으로 URL 경로를 판단합니다.

• src/routes 👉 웹사이트의 루트 경로 (/)가 됩니다.
• src/routes/about 👉 /about 주소로 접속했을 때 실행되는 라우트가 됩니다.
• 중첩 라우팅(Nested Routes): src/routes/trips/new와 같이 폴더 안에 폴더를 깊게 생성하면 그대로 /trips/new라는 중첩된 URL 경로가 완성됩니다.

---

2. 페이지를 정의하는 특수 파일: + 접두사 규칙

라우트 경로에 해당하는 폴더 안에 +로 시작하는 특별한 예약 파일을 정의해야 비로소 페이지나 레이아웃으로 활성화됩니다. + 접두사는 스벨트킷 라우터에게 이 파일들이 일반 컴포넌트가 아닌 라우팅용 특수 파일임을 알려주는 역할을 합니다.

• +page.svelte (UI 화면): 실제 사용자가 브라우저로 해당 경로에 접근했을 때 화면에 보여줄 스벨트 UI 컴포넌트입니다. 초기 요청 시 서버사이드 렌더링(SSR)을 거쳐 완벽한 HTML로 브라우저에 전달되고, 이후 네비게이션 시에는 클라이언트사이드 렌더링(CSR)으로 작동하여 아주 매끄럽게 변경됩니다.
• +page.js / +page.ts (공용 데이터 로딩): 서버와 클라이언트 양쪽에서 모두 실행 가능한 load 함수를 작성하여, 페이지 컴포넌트가 그려지기 전에 필요한 데이터를 미리 가져오도록 처리합니다.
• +page.server.js / +page.server.ts (서버 전용 데이터 로딩 및 액션): 오직 서버에서만 실행되는 파일입니다. 데이터베이스 직접 쿼리나 민감한 환경 변수를 사용해야 할 때 강제되며, 사용자가 입력한 양식을 처리하는 Form Actions(서버 액션)도 이곳에 정의합니다.

---

3. 유연하고 견고한 고급 라우팅 기능

스벨트킷은 대규모 실무 프로젝트를 처리하기 위해 다음과 같은 유연한 하위 폴더/파일명 규칙들을 지원합니다.

• 동적 라우팅 (Dynamic Routes) [slug]: 폴더명을 src/routes/blog/[slug]와 같이 대괄호로 감싸면 동적인 변수 경로를 다룰 수 있습니다. /blog/hello-world에 접속하면 slug 변수에 "hello-world"가 할당되며, 페이지 컴포넌트나 서버 load 함수 내에서 params.slug 형태로 꺼내 쓸 수 있습니다.
• 선택적 매개변수 (Optional Parameters) [[lang]]: [[lang]]/about과 같이 대괄호를 이중으로 사용하면 해당 세그먼트가 생략되어 /about으로 접속하더라도 성공적으로 경로를 매칭해 줍니다.
• 나머지 매개변수 (Rest Parameters) [...file]: src/routes/media/[...file]처럼 작성하면 폴더 하위의 무작위의 모든 슬래시 세그먼트를 변수 배열로 한 번에 가두어 처리할 수 있습니다.
• 경로 매칭 검증 (Route Matchers) [id=matcher]: 동적 주소 값에 특정 형식(예: 정수 패턴만 허용)을 강제하고 싶다면, src/params 폴더에 일치 판별 정규식 파일(예: slug.ts)을 만들고, 폴더명을 [slug=slug]와 같이 매칭명을 지정해 주어 잘못된 접속 시 자동으로 404 에러를 내뱉게 만들 수 있습니다.
• 그룹 라우트 (Route Groups) (app): 폴더명을 (app) 혹은 (admin)과 같이 소괄호로 감싸면, 실제 브라우저의 URL 경로에는 영향을 미치지 않으면서 코드 프로젝트 내에서 라우트 구조를 깔끔하게 그룹 묶음 처리할 수 있습니다. 이를 통해 완전히 다른 UI 레이아웃을 가진 영역들을 독립적으로 격리하기에 유용합니다.
• 레이아웃 탈출 (Breaking out of Layouts): 중첩된 하위 경로의 페이지가 기본적으로 물려받는 상위 레이아웃들의 사슬 관계를 깨뜨리고 싶을 때가 있습니다. 이때는 파일명을 +page@.svelte (루트 레이아웃으로 리셋) 혹은 +page@app.svelte (특정 레이아웃 지정) 형태로 골뱅이(@) 식별자를 붙여 상속할 대상을 명시적으로 지정해 상위 구조를 재정의할 수 있습니다.