프로젝트 구조

SvelteKit은 정해진 폴더와 파일 이름으로 동작을 결정합니다. 이 장에서는 새 프로젝트의 구조, 설정 파일, 그리고 파일 이름 규칙을 살펴봅니다.

기본 폴더 구조

sv create로 만든 TypeScript 프로젝트는 대략 다음과 같습니다.

my-app/
  src/
    lib/                 # 여러 곳에서 쓰는 코드와 컴포넌트
      server/            # 서버에서만 쓰는 코드
    routes/              # 페이지와 API (주소 = 폴더 구조)
      +layout.svelte
      +page.svelte
    app.html             # HTML 틀
    app.d.ts             # 앱 전역 타입(App.Locals 등)
    hooks.server.ts      # 서버 훅(선택)
    hooks.client.ts      # 클라이언트 훅(선택)
    params.ts            # 경로 매개변수 검사기(선택)
  static/                # 그대로 내보낼 파일(robots.txt, favicon 등)
  tests/                 # Playwright 테스트(추가했을 때)
  package.json
  tsconfig.json
  vite.config.ts

src/routes와 src/app.html만 반드시 있어야 하고 나머지는 필요할 때 만듭니다. .svelte-kit/ 폴더는 개발 서버와 빌드가 만들어 내는 생성물이므로 지워도 다시 생기며, 저장소에 넣지 않습니다.

설정 파일: vite.config.ts

SvelteKit 설정은 vite.config.ts에서 sveltekit() 플러그인에 넘깁니다. 예전 판에서 쓰던 svelte.config.js는 현재 판에서 더 이상 쓰지 않으므로, 오래된 자료를 볼 때 주의하세요. 어댑터, 경로, CSRF 같은 SvelteKit 옵션이 모두 여기에 모입니다.

import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    sveltekit({
      adapter: adapter()
    })
  ]
});

일반 Vite 설정(서버 포트, 프록시, 다른 플러그인)도 같은 파일의 defineConfig에 함께 적습니다.

#lib 별칭과 package.json

src/lib의 코드는 #lib 별칭으로 가져옵니다. 이 별칭은 Node.js의 하위 경로 가져오기(subpath imports)이므로 package.json의 imports에 선언되어 있고, 가져올 때 파일 확장자를 붙입니다.

{
  "type": "module",
  "imports": {
    "#lib": "./src/lib/index.js",
    "#lib/*": "./src/lib/*"
  }
}

import { formatDate } from '#lib/date.js';
import Button from '#lib/components/Button.svelte';

이전 판의 $lib 별칭을 쓰는 예제를 보면 #lib와 확장자로 바꿔 읽으면 됩니다. tsconfig.json은 SvelteKit이 만들어 주는 설정을 상속하고, 포함할 파일은 프로젝트에서 직접 정합니다.

경로 파일 이름 규칙

src/routes 안의 폴더가 주소가 되고, +로 시작하는 파일이 그 주소의 역할을 정합니다.

폴더 이름에도 규칙이 있습니다. [slug]는 동적 매개변수, [[lang]]은 생략 가능한 매개변수, [...rest]는 나머지 경로 전체, (group)처럼 괄호로 감싼 폴더는 주소에 나타나지 않고 레이아웃을 묶는 데만 쓰입니다.

src/routes/
  (marketing)/
    +layout.svelte       # 마케팅 페이지 공통 틀
    pricing/+page.svelte # /pricing
  blog/
    +page.svelte         # /blog
    [slug]/
      +page.svelte       # /blog/hello-world
      +page.server.ts
  api/
    search/+server.ts    # /api/search

매개변수 검사기와 훅

경로 매개변수를 검사하려면 src/params.ts 한 파일에 검사기를 모읍니다. 검사기는 받아들일 값이면 그 값을, 아니면 undefined를 돌려줍니다.

import { defineParams } from '@sveltejs/kit/params';

export const params = defineParams({
  fruit: (param) => (param === 'apple' || param === 'orange' ? param : undefined)
});

이렇게 정의하면 src/routes/fruits/[name=fruit]/+page.svelte는 apple과 orange에만 맞습니다. 모든 요청 앞뒤에 끼어드는 코드는 src/hooks.server.ts의 handle 함수에 두며, 다음 장들에서 로그인 정보 같은 요청별 값을 event.locals에 넣는 예를 다룹니다.

정리

• 페이지와 API는 src/routes, 공용 코드는 src/lib, 정적 파일은 static에 둡니다.
• SvelteKit 설정은 vite.config.ts의 sveltekit() 플러그인 옵션으로 넘깁니다.
• src/lib는 #lib 별칭과 확장자를 붙여 가져옵니다.
• +page, +layout, +server, +error 파일 이름과 [param], (group) 폴더 규칙이 라우팅을 결정합니다.