Workflow DevKit 내부 구조: 프레임워크 통합이 동작하는 방법

Vercel 의 Workflow DevKit(WDK)이 Next.js, SvelteKit, Express, Hono 등 서로 다른 프레임워크와 어떻게 호환되는지 내부 구조를 설명하는 글이다. SWC 컴파일러 플러그인이 동일한 소스를 3가지 출력 모드로 변환하고, 프레임워크별 Request 객체 차이를 표준 Web API 로 통일하는 것이 핵심 설계다.

핵심 포인트

모든 WDK 프레임워크 통합은 빌드 타임(번들링·핸들러 생성)과 런타임(HTTP 엔드포인트 노출)의 2단계 패턴을 공통으로 따른다.
SWC 컴파일러 플러그인이 동일한 소스를 client/step/workflow 3모드로 변환해 각각 HTTP 클라이언트 코드, 서버 핸들러, 오케스트레이터를 만든다.
파일 기반 라우팅 프레임워크(Next.js, SvelteKit, Astro)는 생성된 핸들러를 자동 발견하고, HTTP 서버 프레임워크(Express, Hono)는 Nitro 를 통해 가상 핸들러를 마운트한다.
프레임워크마다 다른 Request 객체 형식을 표준 Web Request API 로 변환하는 converter 함수 주입이 프레임워크 중립 호환의 핵심 해법이다.

상세 정리

설계 과제: 각 프레임워크가 서로 다른 요청/응답 형식을 갖고 있어 단일 코드베이스로 모든 프레임워크를 지원하는 것이 핵심 과제였다.
빌드 타임 단계: 워크플로우와 step 함수를 실행 가능한 핸들러로 컴파일하고, 번들링·파일 출력·프레임워크별 호환 패치를 처리한다. HMR 설정도 이 단계에서 완료된다.
런타임 단계: 워크플로우 클라이언트 transform 을 적용하고, 핸들러 파일이 별도 설정 없이 HTTP 엔드포인트로 노출된다.
SWC client 모드: Rollup/Vite 로 처리하며, 워크플로우 호출을 HTTP 클라이언트 코드로 변환하고 workflowId 프로퍼티를 추가한다.
SWC step 모드: esbuild 로 처리, step 함수를 서버 사이드 HTTP 핸들러로 변환한다.
SWC workflow 모드: esbuild 로 처리, 워크플로우 함수를 샌드박스 가상 환경 오케스트레이터로 변환한다.
파일 기반 라우팅 통합: Next.js, SvelteKit, Astro 는 생성된 핸들러 파일을 자동으로 엔드포인트로 인식해 수동 연결이 불필요하다.
HTTP 서버 프레임워크 통합: Express, Hono 는 Nitro 서버 툴킷을 통해 번들링 및 가상 핸들러 마운트 방식으로 통합된다.
Request 형식 통합: 프레임워크별 request 객체를 표준 Web Request API 포맷으로 변환하는 converter 함수를 주입해 WDK 코어가 단일 인터페이스만 처리하도록 추상화한다.
채택 현황: WDK 출시 이후 GitHub 스타 1,300개 이상을 달성했으며, 프레임워크 중립 설계가 채택 장벽을 낮추는 것이 핵심 목표였다.