Vercel 배포 중 React Router v7 빌드 오류 해결기

1. 상황

 한 번 배포 환경에서는 어떻게 보일지 확인해보고 싶어서 vercel을 이용해서 배포하려 했다. 우선 project setting에서 Framework preset에는 React Router가 선택되어 있길래 그대로 둔 후, Environment Variables에 구글 ai studio에서 발급받은 키 값을 추가했다. 그랬더니 이런 에러가 발생했다.

 

 

2. 문제 상황

2-1. SSR 모드

 

 뭔가 이상해서 npm run build 후 확인을 해보니 index.html이 생성되지 않았었다. index.html은 브라우저가 읽을 수 있는 단일 진입점인데 이게 없었다. 근데 React Router v7은 기본 설정(SSR 모드)에서는 빌드 후 index.html 파일이 생성되지 않는다고 한다. 왜냐하면 React Router v7은 단순한 라이브러리를 넘어 풀스택 프레임워크로 동작하기 때문이라고 한다. 근데 우선은 배포 환경에서 확인을 해보고 싶었기 때문에, 우선은 임시로 SPA 모드로 변경할 필요가 있었다.

 

2-2. react-router.config.ts 수정

 react-router.config.ts는 React Router v7 프로젝트의 빌드 방식과 실행 환경을 정의하는 핵심 설정 파일이다. 여기서 렌더링 전략을 결정할 수 있으며(SSR, SPA) presets를 통해 특정 호스팅 플랫폼에 최적화된 설정을 자동으로 주입할 수도 있다고 한다. 그래서 일단 이 파일을 아래와 같이 수정했다.

import type { Config } from "@react-router/dev/config";
 import { vercelPreset } from "@vercel/react-router/vite";

export default {
  presets: [vercelPreset()], // 버셀 배포를 위해 주석 해제 권장
  ssr: false,                // SPA 모드 활성화
  // prerender: ["/", "/history", "/login"], // SPA 모드 확인을 위해 잠시 주석 처리
} satisfies Config;

 

 

이를 통해 build/client/index.html에 결과물에 위치하게 된다.

 

2-3. package.json 수정

 또한 scripts에서 React Router 전용 빌드 명령어를 사용하게 수정해야 한다. 예를 들어 vite build는 Vite 기본 빌드인데, 이는 React Router v7 설정을 반영하지 못할 수도 있기 때문에 react-router build를 이용하게 수정했다.

 

"scripts": {
    "dev": "vite",
    "build": "react-router build",
    "lint": "eslint .",
    "preview": "serve ./build/client",
    "format": "prettier --write .",
    "format:check": "prettier --check ."
  },

 

 

 

2-4. Vercel의 Settings 수정

 

 

 첨부한 이미지처럼 Output Directory도 build/client로 변경했다. Framework Preset은 Vite로 변경했는데 이는 대략 다음과 같은 이유로 변경하였다.

1. React Router v7은 내부적으로 vite를 사용한다고 한다.
2. 프리셋은 기본값 세트일 뿐이다.
3. (react-router.config.ts에서) vercelPreset()가 있기 때문. vercelPreset 설정은 버셀에 배포될 테니 그에 맞게 빌드해주라고 요청하는 역할이라고 한다.

 

물론 React Router로 설정해도 잘 된다.

 

3. 확인

 

이제 배포 환경에서도 잘 확인할 수 있었다.

 

4. 참고 문서

• React Router v7 - SPA Mode