“그냥 Vite를 사용하세요”… Workers 런타임과 함께

2025-04-08

5분 소요

오늘, Cloudflare Vite 플러그인 1.0 출시와 함께 React Router v7에 대한 공식 지원을 발표합니다!

지난 몇 년간 Vite의 눈부신 성장으로 웹 개발에서 가장 인기 있는 빌드 도구 중 하나가 되었으며, 큰 생태계와 활발한 커뮤니티를 보유하게 되었습니다. Cloudflare Vite 플러그인은 Workers 런타임을 Vite의 핵심에 직접 통합합니다! 이전에는 Vite 개발 서버가 항상 서버 코드를 Node.js에서 실행했지만, 실제 배포는 Cloudflare Workers에서 이루어졌습니다. 새롭게 Vite 6에서 실험적으로 도입된 Environment API를 사용하면, 이제 Workers 코드를 네이티브 Cloudflare Workers 런타임(workerd)에서 실행할 수 있습니다. 즉, 개발 서버가 실제 배포 환경과 거의 동일하게 동작하므로, 개발 및 배포 시 높은 신뢰도를 제공합니다.

Vite 6는 탄생 이후 가장 중요한 아키텍처 변화를 포함하고 있어 생태계에 새로운 가능성을 열어줍니다. 그 중심에는 Environment API가 있으며, Vite 개발 서버가 다양한 커스텀 런타임 환경과 상호작용할 수 있게 합니다. 이제 서버 코드를 workerd와 같은 다른 자바스크립트 런타임에서 실행하는 것이 가능해졌습니다.

이 기회에 Vite 팀과 긴밀히 협업하여 디자인과 구현에 참여할 수 있어 감사하게 생각합니다. 직접 그들의 배려와 철저한 노력을 경험해보면, Vite와 그 생태계가 왜 이렇게 건강한지 알 수 있습니다!

Vite 6에서 Cloudflare Worker 환경과 함께

아래 다이어그램에서 흐름을 한눈에 살펴볼 수 있습니다. 사용자가 브라우저에서 페이지를 열면(1), Vite 개발 서버로 요청이 전송됩니다(2). Vite는 요청을 처리하고, 소스 파일을 모듈로 변환하여 클라이언트 및 Worker 환경에 제공합니다. 클라이언트 모듈은 브라우저로 다운로드되어 자바스크립트로 실행되고, Worker 모듈은 Cloudflare Workers 런타임으로 전달되어 서버 측 요청을 처리합니다. 요청이 Worker에서 처리되고(3, 4), Vite 개발 서버가 브라우저로 응답을 반환(5), 사용자는 결과를 확인하게 됩니다(6).

싱글 페이지 애플리케이션

Vite는 React, Vue, Svelte 등 어떤 프론트엔드 프레임워크를 선호하더라도 싱글 페이지 애플리케이션(SPA) 개발의 대표 선택지가 되었습니다.

새 앱 만들기

이제 create-cloudflare CLI를 사용해 새로운 React SPA를 만들며 Cloudflare Vite 플러그인을 체험해 보세요.

npm create cloudflare@latest my-react-app -- --framework=react --platform=workers 이 명령은 내부적으로 create-vite를 실행한 뒤, Cloudflare Vite 플러그인을 적용하는 데 필요한 변경을 가합니다.

아래 버튼을 통해 원하는 Git 저장소와 연결하여 Cloudflare Workers에서 React SPA 프로젝트를 만들고, Cloudflare Workers Builds를 통해 자동으로 배포하며, 새로운 Vite 플러그인까지 적용된 상태로 프로젝트를 시작할 수도 있습니다.

기존 앱 업데이트하기

기존의 Vite SPA 프로젝트에 동일한 기능을 적용하고 싶다면 아래 두 단계만 따라 하면 됩니다.

@cloudflare/vite-plugin을 플러그인 목록에 추가하세요:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { cloudflare } from "@cloudflare/vite-plugin";

// https://vite.dev/config/
export default defineConfig({
  plugins: [react(), cloudflare()],
});

Vite 설정 파일과 같은 위치에 wrangler.jsonc 설정 파일을 추가합니다:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-react-app",
  "compatibility_date": "2025-04-01",
  "assets": {
    "not_found_handling": "single-page-application",
  },
}

프론트엔드 전용 앱의 경우, Cloudflare 플러그인은 Vite 개발 서버를 Workers Assets와 통합하여 html_handling과 not_found_handling 등의 설정이 실제 배포 환경과 동일하게 작동하도록 보장합니다. 하지만 이것은 시작에 불과합니다. 진정한 마법은 Worker 백엔드를 추가하여 개발 및 배포 작업 흐름에 자연스럽게 녹여들 때 시작됩니다.

앱 개발하기

이를 직접 경험하려면, Vite 개발 서버를 실행하세요. 이제 Worker가 Cloudflare Workers 런타임에서 동작합니다:

npm run dev 브라우저에서 첫 번째 버튼을 클릭해 카운터를 몇 번 증가시켜보세요. 브라우저 내 자바스크립트로 동작하는 전통적인 SPA입니다. 두 번째 버튼을 클릭해 API로부터 응답을 받아보세요. Name from API is: Cloudflare라는 메시지가 표시됩니다. 이는 Vite 내에서 실행되는 Cloudflare Worker에 API 요청을 보내고 있는 것입니다.

api/index.ts 파일을 보면, 정적 자산과 일치하지 않는 모든 요청에 대해 Worker가 호출됩니다. 만약 pathname이 /api/로 시작하면 JSON 응답을 반환합니다.

api/index.ts에서 반환하는 name 값을 Cloudflare Workers로 바꾼 뒤 저장하세요. 브라우저에서 두 번째 버튼을 다시 클릭하면, 기존 카운터는 그대로 유지되면서 새로운 이름이 표시됩니다. Vite는 변경 사항을 추적하여 Worker 환경만 업데이트하고, 클라이언트 환경은 그대로 둡니다. Vite와 Cloudflare 플러그인을 사용하면, 클라이언트와 서버 양쪽 코드를 UI 상태 유지하며 동시에 빠르게 반복 개발할 수 있습니다.

Cloudflare Vite 통합은 개발 서버에만 머무르지 않습니다. vite build는 클라이언트와 서버 코드를 한 번에 번들링하며, vite preview로 실제 배포 전 Workers 런타임에서 미리보기할 수 있습니다. 마지막으로, wrangler deploy는 Vite 빌드를 자동 인식하여 추가 번들 과정 없이 바로 배포합니다.

React Router v7

Vite가 처음에는 SPA 빌드 도구로 시작했지만, 이제는 새로운 세대의 풀스택 프레임워크의 기본이 되었습니다. Astro, Qwik, React Router, SvelteKit 등 많은 프레임워크가 Vite의 개발 서버, 빌드 파이프라인, 훌륭한 개발자 경험을 채택했습니다. Environment API뿐만 아니라 Remix 팀과도 Vite 환경 활용에 긴밀히 협력해왔습니다. 오늘, React Router v7 (Remix의 후속)을 Cloudflare Vite 플러그인에서 공식 지원함을 발표합니다.

create-cloudflare CLI로 Cloudflare Vite 플러그인이 설정된 새 React Router 앱을 만들 수 있습니다.

npm create cloudflare@latest my-react-router-app -- --framework=react-router npm run dev로 개발 서버를 시작하세요. npm run build(빌드), npm run preview(미리보기), npm run deploy(배포)도 시도해볼 수 있습니다.

아래 코드는 workers/app.ts의 일부입니다. 이 파일은 wrangler.jsonc의 main 필드에 명시되어 있습니다:

const requestHandler = createRequestHandler(
  () => import("virtual:react-router/server-build"),
  import.meta.env.MODE
);

export default {
  async fetch(request, env, ctx) {
    return requestHandler(request, {
      cloudflare: { env, ctx },
    });
  },
} satisfies ExportedHandler<CloudflareEnvironment>;

이 단일 파일이 개발 및 빌드 시 모두 Worker 정의를 담당하며, 완전한 제어를 제공합니다. 더 이상 빌드 타임 어댑터는 필요하지 않습니다! env와 ctx가 요청 핸들러에 직접 전달되는 것에 주목하세요. 이는 Loader와 Action에서도 접근 가능하며, 서버 코드 전체와 함께 Workers 런타임에서 실행됩니다. 필요에 맞게 이 파일에 다른 내보내기를 추가하고, Worker 설정에서 참조하세요. Durable Object나 Workflow도 쉽게 추가할 수 있습니다!

앞으로 다른 많은 풀스택 프레임워크가 지원될 예정이며, 다양한 팀과 지속적으로 논의와 협업을 이어가고자 합니다. Cloudflare 및/또는 Vite Environment API와의 통합 강화를 원하는 프레임워크 기여자라면 코드를 살펴보고, GitHub 또는 Discord를 통해 언제든 문의해 주세요.

Workers

현재까지는 Vite로 웹 애플리케이션을 빌드하는 데 초점을 맞췄지만, Cloudflare 플러그인을 사용하면 Workers로 할 수 있는 거의 모든 것을 Vite로 빌드할 수 있습니다. KV, D1, Service Bindings, RPC, Durable Objects, Workflows, Workers AI 등 Cloudflare 개발자 플랫폼 전체를 지원합니다. 대부분의 경우, 기존 Worker를 Vite로 개발 환경에 통합하는 것은 다음 두 단계를 거치면 됩니다:

의존성 설치:

npm install --save-dev vite @cloudflare/vite-plugin

Vite 설정 파일 추가:

// vite.config.ts

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
  plugins: [cloudflare()],
});

이게 끝입니다! 플러그인은 기본적으로 프로젝트 루트에서 wrangler.json, wrangler.jsonc, wrangler.toml 중 하나를 찾아 사용합니다. 이제 Vite의 풍부한 플러그인 생태계와 다양한 통합 기능을 활용하여 손쉽게 빌드 결과를 맞춤화할 수 있습니다.

마치며

2024년, 우리는 이전 포스팅에서 Cloudflare 바인딩을 Node 기반 개발 서버에서 접근할 수 있도록 getPlatformProxy()를 소개했습니다. 그 글의 마지막에서 Vite에서 직접 Workers 런타임으로 개발하는 미래를 상상해봤죠. 이는 개발과 실제 배포 환경에서 발생하는 미묘한 차이를 없앨 수 있습니다. 오늘, 그 미래가 현실이 되었고 여러분이 직접 경험해보길 기대합니다!

create-cloudflare CLI로 React Router, React, Vue 템플릿 신규 프로젝트를 시작하거나, 아래 “Deploy to Cloudflare” 버튼을 사용하거나, 기존 Vite 앱에 @cloudflare/vite-plugin만 추가해보세요. 여러분의 멋진 도전을 기다립니다!

자세한 내용은 Cloudflare Vite 플러그인 공식 문서를 참고하세요.

Cloudflare의 연결 클라우드는 전체 기업 네트워크 보호, 인터넷 규모의 애플리케이션 구축 지원, 웹사이트 및 인터넷 애플리케이션 가속, DDoS 방어, 해커 차단, 제로 트러스트 환경 지원 등 다양한 기능을 제공합니다.

어떤 디바이스에서든 1.1.1.1에 방문해 인터넷을 더 빠르고 안전하게 만드는 무료 앱을 이용해보세요.

더 나은 인터넷을 위한 우리의 미션이 궁금하다면 여기서 시작하세요. 새로운 경력을 원한다면 채용 정보도 확인해보세요.

Developer Week Developers Cloudflare Workers