vercel.json을 vercel.ts로 옮기는 방법: 타입 안전한 Vercel 설정 마이그레이션

필드 대조표, routes 헬퍼, 타입 오류 확인, 평가 시점 차이까지 단계별로 정리

vercel.ts 전환 실습 썸네일

핵심 요약

  1. @vercel/config 기반의 vercel.ts는 기존 vercel.json을 대체하며, VercelConfig 타입 검사와 routes.rewrite, routes.redirect, routes.cacheControl 헬퍼를 제공한다.
  2. vercel.ts는 요청마다 돌지 않고 빌드 시점에 정적 라우팅 설정으로 컴파일되므로, 요청별 동적 쿠키/세션 검사가 필요하면 vercel.ts가 아니라 middleware.ts(또는 proxy.ts)를 써야 한다.
  3. 프리뷰 환경과 프로덕션 환경의 크론 잡·리라이트 분기를 주석과 함께 깔끔하게 관리할 수 있어 설정 변경을 코드 리뷰로 추적하기 쉬워진다.

오랫동안 Vercel 프로젝트의 리다이렉트, 보안 헤더, 서버리스 함수 타임아웃, 크론 잡 설정은 정적 JSON 파일인 vercel.json에서 관리해 왔다. 하지만 규칙이 수십 개로 늘어나면 주석을 달 수 없고, 필드명 오타(rewrtes 등)나 정규식 실수를 배포 전까지 잡기 어려우며, 환경 변수에 따른 조건부 분기가 불가능하다는 한계가 있었다. 이 글은 프론트엔드 및 데브옵스 엔지니어가 공식 @vercel/config 패키지를 이용해 기존 vercel.json을 타입 안전한 **vercel.ts**로 마이그레이션하는 절차와 빌드·런타임 평가 시점 차이를 다룬다.

정적 JSON에서 코드로: vercel.ts와 @vercel/config가 바꾸는 세 가지

Vercel 공식 문서와 vercel.ts 마이그레이션 필드 노트에 정리된 핵심 변화는 다음 세 가지로 요약된다.

  1. 컴파일 타임 타입 검증(VercelConfig): IDE 자동완성과 tsc 검사를 통해 허용되지 않는 속성명이나 잘못된 maxDuration 타입, 누락된 필수 필드를 커밋 전에 즉시 잡아낸다.
  2. 라우팅 및 헤더 헬퍼 함수(routes.*): 복잡한 중첩 JSON 배열 대신 routes.rewrite(), routes.redirect(), routes.cacheControl(), routes.header() 같은 선언형 헬퍼를 사용해 가독성을 높인다.
  3. 빌드 시점 동적 분기와 환경 변수 주입(deploymentEnv): 프리뷰(preview) 배포와 프로덕션(production) 배포에 따라 리라이트 대상 도메인을 다르게 지정하거나, deploymentEnv() 헬퍼로 배포 환경 변수를 안전하게 참조할 수 있다.

기존 프로젝트에서 TypeScript로 API 계약이나 환경 설정의 안정성을 높이는 방법이 궁금하다면 TypeScript가 AI 코딩 품질과 유지보수성에 기여하는 원리와 실무 파이프라인을 함께 참고할 수 있다.

주요 필드 매핑 대조표: vercel.json vs vercel.ts

마이그레이션 전에 기존 vercel.json의 각 최상위 필드가 @vercel/config/v1에서 어떤 방식으로 표현되는지 아래 표로 대조한다.

설정 영역기존 vercel.json 방식vercel.ts (@vercel/config/v1) 방식주요 이점
기본 구조{ "$schema": "...", ... }export const config: VercelConfig = { ... }주석 작성, 변수 추출, 모듈 분리 가능
redirects{ "source": "/a", "destination": "/b", "permanent": true }routes.redirect('/a', '/b', { permanent: true })상태 코드(301/308 등)와 옵션 타입 자동 검증
rewrites{ "source": "/api/:path*", "destination": "https://..." }routes.rewrite('/api/(.*)', 'https://.../$1') 및 콜백 지원경로 파라미터 추출 콜백과 요청 헤더 주입 지원
headers중첩된 { "source": "...", "headers": [{ "key": "...", "value": "..." }] }routes.cacheControl('/static/(.*)', { public: true, maxAge: '1 week', immutable: true })사람이 읽기 쉬운 시간 단위('1 week')를 초 단위로 자동 변환
functions{ "app/api/**/*": { "maxDuration": 60 } }functions: { 'app/api/**/*': { maxDuration: 60 } }플랜별 허용 속성 및 숫자 범위 타입 체크
환경 변수 참조정적 JSON이라 직접 참조 불가deploymentEnv('API_UPSTREAM_TOKEN')빌드 시점 코드 평가와 배포 환경 변수 바인딩 분리

단계별 마이그레이션과 타입 오류·평가 시점 확인 실습

실제 Next.js 프로젝트에서 vercel.json을 제거하고 vercel.ts로 전환하는 4단계 절차다.

1단계: 패키지 설치 및 기존 설정 백업

먼저 개발 의존성으로 @vercel/config와 로컬 검증용 Vercel CLI 최신 버전을 설치한다.

npm install -D @vercel/config vercel@latest

주의할 점은 프로젝트 루트에 vercel.json과 vercel.ts가 동시에 존재하면 빌드 시 충돌 오류가 발생한다는 것이다. 기존 vercel.json의 내용을 옮긴 뒤에는 반드시 vercel.json 파일을 삭제(git rm vercel.json)해야 한다.

2단계: vercel.ts 작성 및 헬퍼 적용

프로젝트 루트에 vercel.ts를 생성하고 리다이렉트, 리라이트, 캐시 헤더, 크론 잡을 옮긴다.

// vercel.ts
import { routes, deploymentEnv, type VercelConfig } from "@vercel/config/v1";

const isProd = process.env.VERCEL_ENV === "production";

export const config: VercelConfig = {
  framework: "nextjs",
  cleanUrls: true,
  trailingSlash: false,

  functions: {
    "app/api/ai/**/*": {
      maxDuration: 60,
    },
  },

  crons: isProd
    ? [{ path: "/api/cron/daily-sync", schedule: "0 3 * * *" }]
    : [], // 프리뷰 브랜치에서는 크론 잡 비활성화

  redirects: [
    routes.redirect("/legacy-blog/:slug", "/posts/:slug", { permanent: true }),
  ],

  rewrites: [
    routes.rewrite("/external-api/(.*)", "https://api.example.com/$1", {
      requestHeaders: {
        Authorization: `Bearer ${deploymentEnv("UPSTREAM_API_KEY")}`,
      },
    }),
  ],

  headers: [
    routes.cacheControl("/assets/(.*)", {
      public: true,
      maxAge: "30 days",
      immutable: true,
    }),
  ],
};

3단계: 의도적 타입 오류 발생시켜 검증하기

정적 JSON에서는 놓치기 쉬운 실수가 vercel.ts에서 어떻게 잡히는지 확인해 본다.

// ❌ 타입 오류 예시 1: maxAge에 허용되지 않는 단위 문자열 입력
routes.cacheControl("/assets/(.*)", {
  maxAge: "30 lightyears", // 허용되지 않는 단위 문자열이므로 타입 오류
});

// ❌ 타입 오류 예시 2: redirect 옵션 오타
routes.redirect("/old", "/new", {
  permenant: true, // 알 수 없는 속성이므로 타입 오류
});

터미널에서 npx tsc --noEmit을 실행하면 배포를 트리거하기 전에 위 오류들이 즉시 출력된다. 로컬에서 커밋 전에 자동으로 tsc를 돌리는 구성은 AI 생성 코드에 ESLint·Prettier·tsc를 커밋 전에 자동 적용하기를 참고해 lint-staged에 연결하면 편하다.

4단계: 빌드 시점 평가(process.env) vs 배포 런타임 바인딩(deploymentEnv) 구분

마이그레이션에서 가장 중요한 개념은 vercel.ts 파일 자체가 언제 실행되는가다. vercel.ts는 요청이 들어올 때마다 실행되는 미들웨어(Edge Middleware)가 아니라, 빌드/패키징 시점에 한 번 실행되어 정적 라우팅 매니페스트로 컴파일된다.

  • process.env.VERCEL_ENV: 빌드 시점에 평가되어 crons 배열을 비우거나 도메인 문자열을 분기할 때 사용한다.
  • deploymentEnv('KEY'): 빌드 로그에 민감한 시크릿 평문을 직접 노출하지 않고 Vercel의 배포 라우팅 계층이 런타임 환경 변수를 참조하도록 플레이스홀더를 생성할 때 사용한다.

정적 JSON에서 코드로 바뀌면서 달라지는 팀 코드 리뷰 규칙

설정 파일이 TypeScript 코드가 되면 유연성이 커지는 만큼 팀 차원의 가드레일도 함께 마련해야 한다.

  • 외부 네트워크 호출 및 무거운 연산 금지: vercel.ts는 설정 매니페스트를 생성하는 파일이므로 내부에서 외부 API를 fetch하거나 파일 시스템을 복잡하게 순회하는 코드를 넣으면 빌드 안정성이 떨어진다.
  • CODEOWNERS 지정: 라우팅 규칙이나 보안 헤더(Content-Security-Policy, X-Frame-Options), 함수 타임아웃 변경은 서비스 전체 장애나 비용 증가로 이어질 수 있으므로 .github/CODEOWNERS에 vercel.ts를 등록해 인프라·시니어 리뷰어의 승인을 받도록 고정한다.

초보자가 자주 실수하는 포인트

  • vercel.json을 지우지 않고 vercel.ts를 추가하는 실수: 두 파일이 동시에 있으면 어떤 설정이 우선하는지 모호해져 Vercel 빌드가 실패한다. 전환 즉시 vercel.json을 삭제해야 한다.
  • vercel.ts 안에서 요청(Request) 객체나 사용자 세션을 읽으려 하는 실수: vercel.ts는 빌드 타임에 한 번만 평가된다. 런타임 요청 헤더나 쿠키 값에 따른 조건부 라우팅은 routes.rewrite의 has/missing 조건 객체를 쓰거나 Next.js 미들웨어에서 처리해야 한다.
  • tsconfig.json의 exclude에 루트 파일이 빠져 타입 체크가 누락되는 실수: tsconfig.json의 include 배열에 "vercel.ts"가 포함되어 있는지 확인해야 CI에서 tsc --noEmit이 vercel.ts까지 함께 검사한다.

체크리스트

  • 프로젝트 루트에서 기존 vercel.json을 완전히 제거하고 vercel.ts만 남겼는가?
  • tsconfig.json의 include에 "vercel.ts"가 포함되어 npx tsc --noEmit 실행 시 타입 검사가 수행되는가?
  • 민감한 업스트림 토큰을 리라이트 헤더에 넣을 때 process.env 문자열 결합 대신 deploymentEnv() 헬퍼를 사용했는가?
  • PR 프리뷰 배포 로그에서 컴파일된 Redirects / Rewrites / Headers 규칙 개수가 의도한 대로 반영되었는지 확인했는가?

자주 묻는 질문

Next.js의 next.config.ts에도 redirects와 headers가 있는데 vercel.ts와 어떻게 역할을 나누나요?

프레임워크 내부 라우팅과 강하게 결합된 리다이렉트(예: basePath, i18n 로케일 연동)는 next.config.ts에 두는 것이 로컬 next dev에서도 동일하게 재현되어 편리하다. 반면 서버리스 함수 실행 제한(functions.maxDuration), 크론 잡(crons), CDN 엣지 레벨의 정적 자산 캐시 정책, 다른 백엔드 서비스로의 프록시 리라이트처럼 플랫폼 인프라 성격이 강한 설정은 vercel.ts에서 통합 관리하는 것이 명확하다.

vercel.ts에서 다른 로컬 TypeScript 파일(config/routes.ts 등)을 import해서 분리해도 되나요?

가능하다. 라우팅 규칙이 수백 개에 달하는 서비스라면 도메인별로 배열을 별도 .ts 파일로 나눈 뒤 vercel.ts에서 스프레드 연산자(...blogRedirects)로 합쳐 관리할 수 있다. 단, 런타임 전용 무거운 라이브러리(DB 클라이언트 등)를 함께 import하지 않도록 순수 설정 모듈로만 분리해야 한다.

참고 자료 · 검증 기준

위 자료와 내용을 대조한 날짜: . 도구·서비스 정책은 이후 바뀔 수 있으므로 적용 전 공식 문서를 다시 확인하세요.

이 글은 실제 실무 환경 테스트 및 검증된 기술 자료를 바탕으로 작성되었으며, 환경 변화에 따라 지속적으로 갱신됩니다.