SvelteKit Cloudflare Adapter 설정 가이드 (2025년 7월)

SvelteKit과 Cloudflare를 연동하여 현대적인 웹 애플리케이션을 배포하는 것은 개발자들에게 강력한 성능과 전역 CDN의 이점을 제공합니다. 이 가이드에서는 SvelteKit 프로젝트를 Cloudflare Pages와 Workers에 배포하기 위한 상세한 설정 방법을 다루겠습니다.

Cloudflare Adapter 개요

Adapter의 역할과 종류

SvelteKit의 어댑터는 빌드된 앱을 입력으로 받아서 배포용 출력물을 생성하는 작은 플러그인입니다. Cloudflare 플랫폼을 위한 주요 어댑터들은 다음과 같습니다:

  • @sveltejs/adapter-cloudflare: Cloudflare Workers와 Cloudflare Pages용 (권장)
  • @sveltejs/adapter-cloudflare-workers: Cloudflare Workers Sites용 (deprecated)
  • @sveltejs/adapter-static: 정적 사이트용

현재 @sveltejs/adapter-cloudflare가 모든 SvelteKit 기능을 지원하며 Cloudflare Workers Static Assets와 Cloudflare Pages 모두를 위한 빌드를 생성합니다.

adapter-auto vs adapter-cloudflare

adapter-auto를 사용하는 경우 adapter-cloudflare가 기본적으로 포함되어 설치됩니다. 하지만 Cloudflare를 계속 사용할 계획이라면 직접 adapter-cloudflare로 전환하는 것이 권장됩니다. 이렇게 하면 로컬 개발 중에 event.platform이 에뮬레이트되고, 타입 선언이 자동으로 적용되며, Cloudflare 전용 옵션을 설정할 수 있습니다.

프로젝트 설정

새 SvelteKit 프로젝트 생성

2025년 현재 Svelte 5가 정식 출시되어 최신 기능들을 사용할 수 있습니다. 새로운 SvelteKit 프로젝트를 생성하려면 다음 명령어를 사용합니다:

npx sv create ./

프로젝트 생성 시 다음 옵션들을 선택할 수 있습니다:

  • Template: SvelteKit minimal
  • TypeScript: TypeScript 선택
  • Add-ons: prettier, tailwindcss, sveltekit-adapter 선택
  • Adapter: cloudflare 선택

create-cloudflare CLI 사용

더 간편한 방법으로는 create-cloudflare CLI를 사용할 수 있습니다. 이 도구는 새 프로젝트 디렉터리를 생성하고, SvelteKit의 공식 설정 도구를 시작하며, 즉시 배포할 수 있는 옵션을 제공합니다:

npm create cloudflare@latest my-sveltekit-app -- --framework=svelte

Cloudflare Adapter 설치 및 설정

수동 설치

기존 프로젝트에 Cloudflare 어댑터를 수동으로 설치하려면 다음 명령어를 실행합니다:

npm install -D @sveltejs/adapter-cloudflare

svelte.config.js 설정

svelte.config.js 파일을 다음과 같이 수정합니다:

import adapter from '@sveltejs/adapter-cloudflare';

export default {
  kit: {
    adapter: adapter({
      // 아래는 옵션 설명을 위한 예시입니다
      config: undefined,
      platformProxy: {
        configPath: undefined,
        environment: undefined,
        persist: undefined
      },
      fallback: 'plaintext',
      routes: {
        include: ['/*'],
        exclude: ['<all>']
      }
    })
  }
};

어댑터 옵션 상세 설명

config 옵션

Wrangler 설정 파일의 경로를 지정합니다. wrangler.jsonc, wrangler.json, 또는 wrangler.toml 외의 다른 파일명을 사용하려면 이 옵션으로 지정할 수 있습니다.

platformProxy 옵션

에뮬레이트된 platform.env 로컬 바인딩의 환경설정을 지정합니다. 이 옵션을 통해 로컬 개발 환경에서 Cloudflare의 KV, D1, R2 등의 서비스를 에뮬레이트할 수 있습니다.

Cloudflare Pages 배포 설정

GitHub 리포지토리 연동

Cloudflare Pages에 배포하기 위해서는 먼저 GitHub 리포지토리를 생성하고 코드를 푸시해야 합니다. 다음 단계를 따라 진행합니다:

  • GitHub에서 새 리포지토리 생성
  • 로컬 프로젝트를 Git으로 초기화
  • 코드를 GitHub에 푸시

Cloudflare Pages 프로젝트 생성

Cloudflare 대시보드에서 Pages 프로젝트를 생성할 때 다음 설정을 사용해야 합니다:

  • Framework preset: None
  • Build command: npm run build 또는 vite build
  • Build output directory: .svelte-kit/cloudflare

환경 변수 설정

가장 중요한 환경 변수는 NODE_VERSION입니다. SvelteKit은 Node 16.14 이상을 요구하므로, production과 preview 환경 모두에 다음과 같이 설정해야 합니다:

  • NODE_VERSION: 18 (권장) 또는 16

Node.js 버전 설정이 잘못되면 빌드 실패가 발생할 수 있습니다. Cloudflare Pages의 기본 Node.js 버전은 상당히 오래된 버전이므로 반드시 환경 변수로 지정해야 합니다.

Cloudflare 서비스 바인딩 설정

타입 정의 설정

Cloudflare의 KV, D1, R2 등의 서비스를 사용하려면 src/app.d.ts 파일에 타입 정의를 추가해야 합니다:

/// <reference types="@sveltejs/kit" />
/// <reference types="@sveltejs/adapter-cloudflare" />

declare global {
  namespace App {
    interface Platform {
      env?: {
        MY_KV: KVNamespace;
        MY_DB: D1Database;
        MY_BUCKET: R2Bucket;
        YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;
      };
      context?: {
        waitUntil(promise: Promise<any>): void;
      };
    }
  }
}

서버 코드에서 바인딩 사용

서버 사이드 코드에서는 platform 객체를 통해 Cloudflare 서비스에 접근할 수 있습니다:

// src/routes/api/example/+server.js
export async function GET({ platform }) {
  const value = await platform.env.MY_KV.get('key');
  const result = await platform.env.MY_DB.prepare('SELECT * FROM users').all();

  return new Response(JSON.stringify({ value, result }));
}

로컬 개발 환경 설정

로컬 개발 환경에서 Cloudflare 바인딩을 에뮬레이트하려면 src/hooks.server.js 파일을 설정합니다:

import { dev } from '$app/environment';

let platform;

if (dev) {
  const { getPlatformProxy } = await import('wrangler');
  platform = await getPlatformProxy();
}

export const handle = async ({ event, resolve }) => {
  if (platform) {
    event.platform = {
      ...event.platform,
      ...platform
    };
  }

  return resolve(event);
};

Wrangler 설정

Wrangler CLI 설치

Cloudflare의 CLI 도구인 Wrangler를 설치합니다:

npm install -D wrangler

wrangler.toml 파일 설정

프로젝트 루트에 wrangler.toml 파일을 생성하여 Cloudflare 서비스 바인딩을 정의합니다:

name = "my-sveltekit-app"
compatibility_date = "2024-01-01"

[build]
command = "npm run build"

[[kv_namespaces]]
binding = "MY_KV"
id = "your_kv_namespace_id"

[[d1_databases]]
binding = "MY_DB"
database_name = "your_database_name"
database_id = "your_database_id"

KV 네임스페이스 생성

KV 네임스페이스를 생성하려면 다음 명령어를 사용합니다:

npx wrangler kv:namespace create "MY_NAMESPACE"

생성된 네임스페이스 ID를 wrangler.toml 파일에 추가해야 합니다.

배포 후 설정

커스텀 도메인 설정

Cloudflare Pages에서 커스텀 도메인을 설정하려면 다음 단계를 따릅니다:

  • Cloudflare 대시보드에서 Pages 프로젝트 선택
  • Custom domains > Set up a domain 클릭
  • 사용할 도메인 입력 후 Continue 클릭

서브도메인의 경우 CNAME 레코드를 생성하여 <YOUR_SITE>.pages.dev를 가리키도록 설정해야 합니다.

바인딩 연결

배포 후 Cloudflare 대시보드에서 실제 서비스와 바인딩을 연결해야 합니다:

  • Pages 프로젝트의 Settings > Bindings으로 이동
    • Add > KV namespace (또는 해당 서비스) 선택
  • Variable Name과 실제 서비스를 연결

문제 해결

Node.js 버전 오류

빌드 시 Node.js 버전 관련 오류가 발생하면 환경 변수에서 NODE_VERSION을 올바르게 설정했는지 확인합니다. SvelteKit 1.1.1 이상에서는 Node 16.14 이상이 필요하며, Node 17은 지원하지 않습니다.

404 오류

배포 후 404 오류가 발생하면 빌드 출력 디렉터리가 .svelte-kit/cloudflare로 올바르게 설정되었는지 확인합니다. 또한 fallback 옵션을 적절히 설정했는지도 점검해야 합니다.

Node.js 호환성 문제

Auth.js 등의 Node.js 모듈을 사용할 때 node:crypto 오류가 발생하면 wrangler.toml에 호환성 플래그를 추가해야 합니다:

compatibility_flags = ["nodejs_compat"]

성능 및 최적화

Workers 제한사항 이해

Cloudflare Workers에는 10ms CPU 시간 제한이 있지만, 2025년 현재 최대 CPU 시간이 5분으로 확장되었습니다. 대부분의 SvelteKit 애플리케이션에서는 이 제한이 문제가 되지 않습니다.

CDN 및 캐싱 활용

Cloudflare Pages는 전역 CDN을 통해 콘텐츠를 제공하므로 이미지 변환 및 최적화 기능을 활용할 수 있습니다. 정적 자산은 static/ 폴더에 배치하여 CDN을 통해 효율적으로 서빙됩니다.

SvelteKit과 Cloudflare의 결합은 현대적인 웹 애플리케이션 개발과 배포를 위한 강력한 솔루션을 제공합니다. 이 가이드에서 다룬 설정을 통해 자동 배포, 전역 CDN, 그리고 다양한 Cloudflare 서비스를 활용할 수 있습니다.

중요한 점은 올바른 Node.js 버전 설정, 적절한 어댑터 구성, 그리고 서비스 바인딩의 정확한 연결입니다. 이러한 설정을 통해 개발자는 높은 성능과 안정성을 갖춘 웹 애플리케이션을 효율적으로 배포할 수 있습니다.

오소리
오소리
꿀통을 찾아다니는 오소리입니다.
작성자 글 모아보기
©YozmBlog
koenjaesfr