SvelteKit 어댑터 — 어디서든 배포하기

"Write once, deploy anywhere" — SvelteKit의 어댑터 시스템은 빌드 출력을 배포 환경에 맞게 변환합니다.

개념 정의

어댑터(Adapter) 는 SvelteKit 앱을 특정 배포 환경에 맞는 형식으로 변환하는 플러그인입니다. 같은 코드를 Node.js 서버, 서버리스 함수, 정적 사이트 등 다양한 형태로 빌드할 수 있습니다.

주요 어댑터

어댑터	대상 환경	설치
`@sveltejs/adapter-auto`	자동 감지	기본 포함
`@sveltejs/adapter-node`	Node.js 서버	`npm i -D @sveltejs/adapter-node`
`@sveltejs/adapter-static`	정적 사이트	`npm i -D @sveltejs/adapter-static`
`@sveltejs/adapter-vercel`	Vercel	`npm i -D @sveltejs/adapter-vercel`
`@sveltejs/adapter-cloudflare`	Cloudflare Pages	`npm i -D @sveltejs/adapter-cloudflare`
`@sveltejs/adapter-netlify`	Netlify	`npm i -D @sveltejs/adapter-netlify`

설정

JAVASCRIPT

// svelte.config.js
import adapter from '@sveltejs/adapter-node';

export default {
  kit: {
    adapter: adapter({
      out: 'build',
      precompress: true,  // gzip/brotli 압축
      envPrefix: '',
    })
  }
};

adapter-node (셀프 호스팅)

JAVASCRIPT

// svelte.config.js
import adapter from '@sveltejs/adapter-node';

export default {
  kit: {
    adapter: adapter({
      out: 'build',
      precompress: true,
    })
  }
};

BASH

# 빌드 & 실행
npm run build
node build/index.js
# PORT=3000 node build/index.js

DOCKERFILE

# Docker 배포
FROM node:20-slim
WORKDIR /app
COPY build ./build
COPY package.json .
RUN npm ci --omit=dev
EXPOSE 3000
CMD ["node", "build/index.js"]

adapter-static (정적 사이트)

JAVASCRIPT

// svelte.config.js
import adapter from '@sveltejs/adapter-static';

export default {
  kit: {
    adapter: adapter({
      pages: 'build',
      assets: 'build',
      fallback: '404.html',  // SPA 모드면 'index.html'
    })
  }
};

JAVASCRIPT

// src/routes/+layout.js
// 모든 페이지를 정적으로 프리렌더
export const prerender = true;

adapter-vercel

JAVASCRIPT

// svelte.config.js
import adapter from '@sveltejs/adapter-vercel';

export default {
  kit: {
    adapter: adapter({
      runtime: 'nodejs20.x',
      regions: ['icn1'],  // 서울 리전
      split: false,
    })
  }
};

adapter-cloudflare

JAVASCRIPT

// svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare';

export default {
  kit: {
    adapter: adapter({
      routes: {
        include: ['/*'],
        exclude: ['<all>'],
      }
    })
  }
};

어댑터 선택 가이드

PLAINTEXT

정적 콘텐츠만? → adapter-static
├── 블로그, 문서 사이트
└── GitHub Pages, S3, CDN

서버 사이드 렌더링 필요?
├── 셀프 호스팅? → adapter-node (Docker, VPS)
├── Vercel? → adapter-vercel
├── Cloudflare? → adapter-cloudflare
└── 잘 모르겠다? → adapter-auto (배포 플랫폼 자동 감지)

면접 포인트

"어댑터가 왜 필요한가요?": SvelteKit은 플랫폼에 독립적인 코드를 작성하고, 어댑터가 빌드 출력을 각 플랫폼에 맞게 변환합니다. 배포 환경이 바뀌어도 앱 코드를 수정할 필요가 없습니다.
"adapter-auto는 어떻게 동작하나요?": 배포 환경을 자동 감지합니다. Vercel에서 빌드하면 adapter-vercel처럼, Netlify에서 빌드하면 adapter-netlify처럼 동작합니다.

정리

어댑터 시스템은 SvelteKit의 "어디서든 배포" 철학을 실현하는 핵심입니다. 앱 코드는 동일하게 유지하면서 svelte.config.js의 어댑터 설정만 바꾸면 Node.js 서버, 서버리스, 엣지, 정적 사이트 어디든 배포할 수 있습니다.