React SPA에서 404 오류 해결하기: `serve`를 활용한 정적 서버 설정

React로 개발한 Single Page Application(SPA)의 빌드파일을 테스트할 때 문제 중 하나가 404 오류다. 특히 브라우저에서 URL을 직접 입력하거나 새로고침했을 때 이 문제가 발생할 가능성이 크다. 이 글에서는 그 원인과 이를 해결하는 방법을 다루며, serve를 활용한 간단한 해결책을 소개한다.

---

404 오류의 원인

SPA는 클라이언트 측 라우팅을 기반으로 동작한다. 예를 들어 http://localhost:3000/disks/list 경로로 이동하면 브라우저는 이를 서버에 요청한다. 하지만 서버는 해당 경로에 대응하는 파일을 찾으려고 하며, 결과적으로 404 Not Found 오류를 반환한다. 이는 정적 파일 서버가 동적 라우팅을 처리하지 못하기 때문이다.

---

해결 방법: serve를 활용한 SPA 모드

이 문제를 해결하려면 모든 경로 요청을 SPA의 진입점인 index.html로 리디렉션해야 한다. 이를 위해 serve 도구의 SPA 모드를 활용할 수 있다.

---

serve 설치 및 실행 방법

1. yarn dlx를 활용한 실행
   최신 yarn 버전에서는 글로벌 설치 대신 yarn dlx로 패키지를 바로 실행할 수 있다. 아래 명령어를 사용하면 dist 폴더를 SPA 모드로 실행할 수 있다.

   yarn dlx serve -s dist

   여기서 -s 옵션은 SPA 모드를 활성화하여 모든 요청을 index.html로 리디렉션한다. 따라서 URL을 직접 입력하거나 새로고침해도 오류가 발생하지 않는다.

2. 결과 확인
   위 명령을 실행한 후 브라우저에서 http://localhost:3000으로 접속하면 앱이 정상적으로 동작한다. URL을 직접 입력하거나 다른 경로로 이동해도 문제없이 작동한다.

---

serve의 장점

• 간편한 설정: 별도의 서버 설정 없이 명령어 하나로 실행 가능하다.
• SPA 지원: React, Vue 등 클라이언트 라우팅을 사용하는 모든 SPA에 적합하다.
• 가벼운 도구: 설치와 실행이 빠르며, 로컬 개발 환경에서 이상적이다.

---

추가 설정 (선택 사항)

1. serve를 로컬에 설치
   프로젝트에 의존성을 추가해 package.json의 스크립트로 관리할 수도 있다.

   yarn add serve --dev

   이후 package.json에 다음과 같은 스크립트를 추가한다.

   {
     "scripts": {
       "start": "serve -s dist"
     }
   }

   이제 아래 명령으로 앱을 실행할 수 있다.

   yarn start

2. 프로덕션 환경
   serve는 주로 로컬 개발 환경에서 사용되며, 프로덕션에서는 Nginx 같은 웹 서버를 사용하는 것이 좋다. Nginx 설정은 아래와 같이 간단히 구현할 수 있다.

   location / {
       root /path/to/dist;
       index index.html;
       try_files $uri /index.html;
   }

---

마무리

serve는 React SPA를 빠르게 테스트하거나 로컬에서 실행하기에 적합한 도구다. 특히 SPA 모드를 활용하면 URL 입력과 새로고침 문제를 간단히 해결할 수 있다. 필요에 따라 로컬 설치, 스크립트화, 프로덕션 배포 방법을 조합해 활용하면 더욱 편리하다.

이제 404 오류로부터 자유로운 개발 환경을 만들어보자!