Introducing Vovk.ts — A Back-End Framework Native to Next.js

Context

Next.js 프로젝트에서 Route Handlers로 API를 구현할 때 구조화된 백엔드 아키텍처(컨트롤러, 서비스 분리)와 타입 안전성을 동시에 확보하기 어렵다. NestJS 수준의 개발 경험을 원하면서도 Next.js의 배포 모델을 벗어나고 싶지 않은 개발자들의 불편함이 있었다.

Technical Solution

• Zod, Valibot, ArkType을 이용한 인플레이스 검증: 컨트롤러 메서드 내부에 @procedure 데코레이터로 params, output 스키마를 정의해 별도 DTO 파일 제거
• 타입 안전 RPC 클라이언트 자동 생성: CLI가 컨트롤러 정의를 읽어 vovk-client 라이브러리로 제공하며 점프-투-정의, JSDoc 호버 지원
• 로컬 프로시저 실행 경로 제공: .fn() 메서드로 HTTP 왕복 없이 SSR, PPR, 백그라운드 작업에서 동일 프로시저 실행
• OpenAPI 3.1 자동 생성: Scalar 호환 문서화를 함께 제공하며 컨트롤러 변경 시 스펙이 자동 동기화
• AI 도구 자동 파생: deriveTools() 호출로 LLM 에이전트와 MCP 서버에서 바로 사용 가능한 도구 정의 생성
• 세그먼트별 서버리스 컴파일: 각 route.ts가 독립적인 함수로 컴파일되어 독립적 런타임 설정 가능
• JSON Lines 스트리밍 지원: 비동기 제너레이터 함수로 스트리밍 응답 구현

Key Takeaway

Next.js 기반 프로젝트에서 컨트롤러 기반 API 구조를 원한다면, 단일 소스 정의에서 클라이언트 생성, OpenAPI 문서화, 로컬 실행 경로, AI 도구 파생을 모두 얻을 수 있는 구조를 설계하는 것이 개발 속도와 타입 안전성을 동시에 높인다.