SvelteKit으로 시작하는 SSR 백엔드-프론트 기초 100단계: 1단계 — 프로젝트 생성하고 “SSR이 돌아가는 상태” 만들기

SvelteKit으로 시작하는 SSR 백엔드-프론트 기초 100단계: 1단계 — 프로젝트 생성하고 “SSR이 돌아가는 상태” 만들기

솔직히 주니어 때 제일 빨리 느는 루트는 이거였어요.
“한 프로젝트 안에서 SSR로 화면 만들고(프론트), 같은 프로젝트 안에서 서버 코드(+page.server)로 데이터도 다뤄보는 경험.”
SvelteKit은 그 동선이 깔끔해서, 초반에 삽질을 덜 하게 해줍니다. 

이번 글(1단계)은 “프로젝트 생성 → 개발 서버 실행 → SSR이 실제로 동작하는지 확인 → 첫 페이지를 SSR 방식으로 바꿔보기” 까지 갑니다.
(오늘 이거 한 번 해두면, 다음 단계에서 DB 붙이고 auth 붙일 때 덜 무섭습니다.)

---

1단계 목표

• SvelteKit 프로젝트를 공식 방식으로 생성한다 (npx sv create)
• 개발 서버를 띄운다 (npm run dev)
• “SSR이 기본으로 켜져서 서버에서 먼저 렌더링되고 → 브라우저에서 hydration 되는 흐름”을 눈으로 확인한다 
• +page.server.ts를 만들어서 서버에서만 실행되는 코드를 한 번 돌려본다(SSR 감각 잡기) 

---

준비물

• Node.js (권장: LTS)
• 터미널(윈도우면 PowerShell/Windows Terminal 추천)
• VS Code

---

Step 1-1. 프로젝트 생성 (공식 커맨드)

SvelteKit 공식 문서 기준, 가장 쉬운 시작은 이거예요. 

npx sv create sveltekit-ssr-100
cd sveltekit-ssr-100
npm install
npm run dev

• sv create는 Svelte/SvelteKit 프로젝트를 만들기 위한 공식 CLI입니다.
• 실행하면 중간에 선택 프롬프트가 뜰 텐데, 여기서 TypeScript를 선택해두는 걸 추천합니다(주니어일수록 타입이 “가드레일”이 됩니다). 

개발 서버가 뜨면 브라우저에서:

• http://localhost:5173 접속

---

Step 1-2. “SSR이 기본으로 동작한다” 감각 잡기

SvelteKit은 기본적으로 서버에서 먼저 HTML을 렌더링해서 보내고, 브라우저에서 다시 렌더링하며 인터랙티브하게 만드는 hydration 흐름을 탑니다. 

이 말을 “그냥 그렇구나”로 끝내면 재미없으니까, 바로 확인해봅시다.

---

Step 1-3. 서버에서만 실행되는 코드 한 번 찍어보기 (+page.server.ts)

SvelteKit에서 +page.server.ts는 이름 그대로 서버에서만 실행되는 파일이에요. SSR로 처음 진입할 때도 실행되고, 내부 네비게이션을 해도 서버에서 실행됩니다(서버 전용 로직을 두는 자리). 

프로젝트 루트에서 아래 파일을 만들어 주세요:

src/routes/+page.server.ts

import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async () => {
	// 서버 터미널에만 찍혀야 정상입니다.
	console.log('[server] +page.server.ts load() is running');

	return {
		serverTime: new Date().toISOString(),
		message: 'SSR: this value was created on the server'
	};
};

이제 기존 홈 화면에서 load 결과를 받아서 보여주겠습니다.

src/routes/+page.svelte

<script lang="ts">
	export let data: { serverTime: string; message: string };
</script>

<h1>Step 1: SvelteKit SSR is running</h1>

<p>{data.message}</p>
<p>Server time: {data.serverTime}</p>

이 상태로 브라우저를 새로고침(F5)하면:

• 터미널(서버) 로그에
  "[server] +page.server.ts load() is running"
  이 찍힙니다.
• 브라우저에는 서버 시간이 렌더링되어 보입니다.

이게 바로 “SSR로 서버에서 값 만들어서 내려주는 흐름” 첫 경험이에요. (다음 단계에서 이 자리에 DB 조회가 들어갑니다.)

---

Step 1-4. 주니어가 여기서 꼭 알아야 하는 개념 3개만

1) +page.svelte는 “화면(UI)”

• 브라우저에서 보이는 컴포넌트

2) +page.server.ts는 “서버 전용 로직”

• DB 접속, 비밀키, 서버 로그, 권한 체크 같은 건 여기에 둡니다.

3) SSR은 기본이 “서버 렌더 → 클라 hydration”

• 보통은 SSR을 끄는(ssr = false) 게 권장되지 않습니다. 

---

자주 터지는 문제 & 해결 (1단계에서 많이 나옵니다)

1) npx sv create가 안 돼요

• Node 버전이 너무 낮은 경우가 많아요. Node를 최신 LTS로 올리고 다시 시도해보세요.
• 회사 PC면 권한 문제로 막힐 수 있어요. 이때는 관리자 권한 터미널로 실행하거나, 설치 경로/권한을 점검합니다.

2) 브라우저는 바뀌는데 터미널 로그가 안 찍혀요

• +page.server.ts 경로가 src/routes/+page.server.ts가 맞는지 확인
• 파일명이 +page.server.js가 아니라 +page.server.ts여도 동작합니다(타입스크립트 프로젝트면). 

---

오늘(1단계) 끝나면 남는 것

• “SvelteKit 프로젝트를 만들고”
• “SSR로 서버에서 데이터를 만들어 내려주고”
• “서버/클라 코드 경계가 어디인지”
  이게 손에 잡힙니다.

이게 잡히면, 다음 단계(2단계)에서 바로 **Form Actions로 ‘쓰기(POST)’**를 해볼 거예요.
SvelteKit은 load가 읽기라면, actions가 쓰기입니다. 

---

 

SvelteKit,SSR,주니어개발자,풀스택,프론트엔드,백엔드,TypeScript,웹개발,사이드프로젝트,로드맵