Svelte_SvelteKit

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

ethanjoh 2026. 7. 7. 23:29

 

스벨트킷(SvelteKit) 프로젝트는 **"설정보다는 규약(Convention over Configuration)"**을 중요하게 여기기 때문에 구조가 직관적이고 일관적입니다. 비트(Vite)와 sv CLI를 통해 생성한 스벨트킷 프로젝트의 핵심 폴더 및 파일 구조는 다음과 같습니다.

 

1. src (소스 폴더) — 프로젝트의 심장

개발자가 작성하는 코드의 99.9%가 위치하는 가장 중요한 폴더입니다.

  • routes/ (라우트 폴더): 스벨트킷은 파일 시스템 기반 라우팅을 사용합니다. 폴더 구조가 그대로 웹사이트의 URL 주소가 되며, + 접두사가 붙은 파일들이 고유의 역할을 수행합니다.
    • +page.svelte: 특정 경로의 화면(UI)을 렌더링하는 컴포넌트입니다.
    • +page.js / +page.ts: 클라이언트와 서버 양쪽에서 실행되며, 페이지가 그려지기 전에 데이터를 불러오는 load 함수를 정의합니다.
    • +page.server.js / +page.server.ts: 오직 서버에서만 실행되는 파일입니다. 데이터베이스 호출이나 API 키 등 브라우저에 노출되면 안 되는 민감한 로직을 처리하거나, Form Actions를 정의해 데이터를 기록할 때 사용합니다.
    • +layout.svelte: 하위 페이지들을 감싸는 공통 레이아웃입니다 (예: 헤더, 푸터, 내비게이션 바 등). 이 역시 데이터를 로드하는 +layout.js 또는 +layout.server.js 파일을 나란히 둘 수 있습니다.
    • +error.svelte: 에러 발생 시 사용자에게 보여줄 커스텀 에러 페이지입니다. 에러가 발생한 가장 가까운 경로의 에러 페이지가 실행됩니다.
    • +server.js / +server.ts: UI 페이지가 아닌, 완전히 커스텀한 **API 엔드포인트(GET, POST, DELETE 등)**를 작성할 때 사용합니다.
  • lib/ (라이브러리 폴더): 프로젝트 전역에서 공통으로 사용할 자식 컴포넌트, 유틸리티 함수, 전역 상태(Store) 등을 보관합니다. 스벨트킷에서는 이 폴더를 **$lib이라는 특별한 별칭(Alias)**으로 지정해 주므로, 복잡한 상대 경로(../../) 대신 편하게 임포트할 수 있습니다.
  • app.html: 서버사이드 렌더링(SSR) 시 스벨트킷이 헤더와 바디의 내용물(Placeholder)을 채워 넣을 수 있게 설계된 애플리케이션의 기본 HTML 템플릿 파일입니다.
  • app.d.ts: 스벨트킷 전역 타입 선언 파일로, 공통으로 활용할 타입 정보나 미들웨어 데이터를 관리할 때 수정하게 됩니다.
  • hooks.server.js / hooks.client.js: 서버나 클라이언트 요청을 가로채 동작하는 미들웨어(인증, 로그 처리, 응답 수정 등) 역할을 수행하는 훅(Hooks) 파일입니다.

2. 기타 주요 폴더들

  • static/ (정적 자산 폴더): 이미지, 파비콘(favicon.png), robots.txt 등 빌드 과정 없이 웹사이트 루트 경로(/)를 통해 그대로 공개되어야 하는 정적 파일들을 보관합니다. 여기에 비밀번호나 API 보안 키 같은 민감한 정보를 넣어서는 절대 안 됩니다.
  • .svelte-kit/: 스벨트킷이 개발 서버 구동 및 빌드 과정에서 자동으로 생성하는 임시 폴더입니다. 자동 생성되는 TypeScript 정의 파일($types.d.ts) 등이 보관되며, 폴더를 삭제해도 다시 실행할 때 알아서 재생성되므로 커밋이나 수정에서 제외하면 됩니다.
  • node_modules/: 프로젝트 구동에 필요한 외부 의존성 패키지들이 다운로드되어 보관되는 라이브러리 폴더입니다.
  • tests/: Playwright 등을 활용한 종단간 테스트(E2E Testing) 코드가 보관되는 영역입니다.

3. 프로젝트 최상위 설정 파일들

  • svelte.config.js: 스벨트 컴파일러와 배포 타겟을 설정하는 어댑터(Adapter) 설정을 기록하는 파일입니다.
  • vite.config.js: 스벨트킷의 강력한 초고속 개발 빌드 도구인 Vite(비트) 설정 파일입니다.
  • package.json: 프로젝트 정보, 설치된 라이브러리 목록, 개발 서버 실행(npm run dev) 및 빌드 스크립트 명령어가 정의된 핵심 명세서입니다.
  • tsconfig.json / jsconfig.json: 프로젝트 코드의 분석 및 타입 지원 환경을 확장해주는 TypeScript/JavaScript 설정 파일입니다.

 

 

 

 

 

 

저작자표시 비영리 변경금지 (새창열림)