React Router v6에서 v7으로 업그레이드하기 — 달라진 점과 실전 마이그레이션 가이드

이전 글에서 피그마로 생성한 React 코드에 React Router v6를 설정하는 방법을 다뤘습니다. 이번 글에서는 React Router v7으로 업그레이드할 때 무엇이 달라지는지, 기존 v6 코드를 어떻게 바꿔야 하는지 정리합니다.

React Router v7에서 달라진 핵심 변경 사항

React Router v7 업그레이드의 가장 큰 특징은 "기존 Future Flag를 모두 켜둔 프로젝트라면 깨지는 것이 없다"는 점입니다. React Router 팀은 v6 후반부터 v7의 변경 사항을 Future Flag 형태로 미리 제공했고, 이 플래그들을 켜둔 프로젝트는 버전만 올리면 됩니다.

주요 변경 사항은 다음과 같습니다.

항목	v6	v7
패키지	react-router-dom 별도 설치	react-router 하나로 통합
라우트 정의	JSX 컴포넌트 방식	객체 기반 Data Router 기본
데이터 로딩	useEffect 직접 호출	loader 함수로 라우트에 선언
번들 크기	기준	약 15% 감소
Splat 경로	* 단일 세그먼트	다중 세그먼트 splat 지원

패키지 통합 — react-router-dom이 사라졌습니다

v6에서는 react-router와 react-router-dom을 구분해서 설치했습니다. v7에서는 react-router 하나로 통합되었습니다. 기존에 react-router-dom에서 가져오던 모든 것을 react-router에서 import하면 됩니다.

변경 전 (v6)

[code lang="js"] import { BrowserRouter, Routes, Route } from 'react-router-dom'; import { Link, NavLink } from 'react-router-dom'; [/code]

변경 후 (v7)

[code lang="js"] import { BrowserRouter, Routes, Route } from 'react-router'; import { Link, NavLink } from 'react-router'; [/code]

패키지도 교체합니다.

[code lang="bash"] npm uninstall react-router-dom npm install react-router [/code]

Data Router — 라우트 정의 방식의 변화

v6에서도 createBrowserRouter를 사용할 수 있었지만 선택 사항이었습니다. v7에서는 이 객체 기반 Data Router가 기본 권장 방식이 되었습니다.

v6 방식 (JSX)

[code lang="js"] function App() { return ( <Route path="/" element={} /> <Route path="/about" element={} /> <Route path="/products" element={} /> <Route path="*" element={} /> ); } [/code]

v7 권장 방식 (Data Router)

[code lang="js"] import { createBrowserRouter, RouterProvider } from 'react-router';

const router = createBrowserRouter([ { path: '/', element: }, { path: '/about', element: }, { path: '/products', element: , loader: async () => { const res = await fetch('/api/products'); return res.json(); }, }, { path: '*', element: }, ]);

function App() { return ; } [/code]

기존 JSX 방식도 v7에서 여전히 작동합니다. 다만 loader, action 같은 Data API 기능을 사용하려면 Data Router 방식으로 전환해야 합니다.

loader 함수 — useEffect를 대체하는 데이터 로딩

v6에서는 컴포넌트 안에서 useEffect로 데이터를 불러오는 것이 일반적이었습니다. v7의 Data Router에서는 loader 함수를 라우트 정의에 직접 선언합니다.

v6 방식 (useEffect)

[code lang="js"] function Products() { const [products, setProducts] = useState([]);

useEffect(() => { fetch('/api/products') .then(res => res.json()) .then(data => setProducts(data)); }, []);

return ; } [/code]

v7 방식 (loader)

[code lang="js"] // 라우트 정의에서 { path: '/products', element: , loader: async () => { const res = await fetch('/api/products'); return res.json(); }, }

// 컴포넌트에서 import { useLoaderData } from 'react-router';

function Products() { const products = useLoaderData(); return ; } [/code]

loader 방식의 장점은 페이지 전환 시 데이터를 미리 불러오기 때문에, 화면이 깜빡이는 현상이 줄어든다는 점입니다. 컴포넌트가 렌더링되는 시점에는 데이터가 이미 준비되어 있습니다.

단계별 마이그레이션 절차

실제로 v6 프로젝트를 v7으로 옮기는 순서입니다.

1단계: Future Flag 먼저 켜기

v6 최신 버전(6.30+)에서 v7의 변경 사항을 미리 적용할 수 있습니다. 한꺼번에 바꾸지 말고 하나씩 켜면서 테스트합니다.

[code lang="js"] <BrowserRouter future={{ v7_startTransition: true, v7_relativeSplatPath: true, }}

[/code]

2단계: 패키지 교체

[code lang="bash"] npm uninstall react-router-dom npm install react-router [/code]

3단계: import 경로 수정

프로젝트 전체에서 react-router-dom을 react-router로 일괄 치환합니다.

AI에게 요청할 때 이렇게 말하면 됩니다: "이 프로젝트에서 react-router-dom import를 모두 react-router로 바꿔줘. 기능은 그대로 유지해야 해."

4단계: Data Router 전환 (선택)

기존 JSX 방식이 잘 작동한다면 이 단계는 나중에 해도 됩니다. loader나 action이 필요한 페이지부터 점진적으로 전환하는 것을 권장합니다.

5단계: 배포 및 테스트

서버 설정(Nginx, Apache, Vercel, Netlify)은 v6과 동일합니다. React 배포 가이드에서 플랫폼별 설정을 확인할 수 있습니다.

지금 업그레이드해야 할까?

결론부터 말하면, 급하지 않습니다. v6는 여전히 유지보수되고 있고, 보안 패치도 계속 나옵니다. 다만 다음 경우에는 v7으로 전환하는 것이 유리합니다.

• 새 프로젝트를 시작하는 경우 — 처음부터 v7로 시작하는 것이 낫습니다
• 페이지 전환 시 로딩 상태 관리가 복잡해진 경우 — loader가 이 문제를 깔끔하게 해결합니다
• 번들 크기를 줄이고 싶은 경우 — 약 15% 감소 효과가 있습니다
• Remix에서 마이그레이션하는 경우 — v7이 Remix와 통합되었습니다

정리

React Router v7 업그레이드의 핵심은 패키지 통합(react-router 하나), Data Router 기본화, loader 함수 도입입니다. Future Flag를 미리 켜두면 v7로의 전환은 패키지 교체와 import 경로 수정만으로 끝납니다. 기존 v6 코드가 당장 깨지지는 않으니, 프로젝트 상황에 맞춰 점진적으로 전환하면 됩니다.