Next.js 앱 라우터와 함께한 1년 — 우리가 떠나기로 한 이유

직장에서 웹 앱 개발에 Next.js를 전문적으로 사용해오면서, 앱 라우터와 리액트 서버 컴포넌트(React Server Components, RSC)의 핵심 설계가 매우 답답하게 느껴졌습니다. 사소한 버그나 API의 혼란스러움이 아니라, Vercel과 리액트 팀이 이를 구축할 때 내린 근본적인 설계 결정에 대한 큰 이견이 있기 때문입니다.

웹 개발 행사에 갈때마다 Next.js를 싫어함에도 계속 사용해야 하는 사람들을 더 많이 보게 됩니다. 이 글의 마지막에는 저와 동료들이 어떻게 이 지옥에서 탈출하여 전체 프론트엔드를 TanStack Start로 원활하게 마이그레이션했는지 공유하겠습니다.

§기술 리뷰: 서버 컴포넌트란 무엇인가요?

RSC의 핵심은 컴포넌트를 "서버" 컴포넌트와 "클라이언트" 컴포넌트 두 가지 범주로 분류한다는 점입니다. 서버 컴포넌트는 useState나 useEffect를 사용하지 않지만, async function일 수 있으며 데이터베이스에 직접 호출하는 등 백엔드 도구를 참조할 수 있습니다. 클라이언트 컴포넌트는 기존 모델로, 백엔드에서 HTML 텍스트를 생성하는 코드와 window.document.*를 사용하여 DOM을 관리하는 프론트엔드 코드가 존재합니다.

첫 번째 재앙: 명명법!! 리액트는 이제 기존 정의를 무시하고 "서버"와 "클라이언트"라는 단어를 매우 특정한 개념을 가리키는 데 사용하고 있습니다. 클라이언트 컴포넌트도 백엔드에서 실행될 수 있다는 점을 제외하면 괜찮을 텐데요! 이 글에서는 웹 앱이 존재하는 두 가지 실행 환경, 즉 Node.js 프로세스와 웹 브라우저를 각각 설명하기 위해 "백엔드"와 "프론트엔드"라는 용어를 사용할 것입니다.

이 "서버"/"클라이언트" 컴포넌트 모델은 흥미롭습니다. <Suspense /> 같은 내장 컴포넌트가 네트워크를 통해 직렬화되기 때문에, 비동기 서버 컴포넌트로 데이터 가져오기를 아주 간단하게 모델링할 수 있으며, 폴백 UI는 마치 클라이언트 측에서 작동하는 것처럼 동작합니다.

//  이 글에서 서버 컴포넌트는 빨간색으로 강조 표시됩니다.
export default async function Page({ params }) {
    // Page 매개변수는 해결된 프로미스로 제공됩니다
    const { username } = await params;

    // `UserInfo` 및 `UserPostList` 컴포넌트는 동시에 실행됩니다.
    // `UserInfo`가 준비되면, 방문자는 게시물 목록이 아직 준비되지 않은 경우
    // `PostListSkeleton`이 포함된 페이지를 보게 됩니다.
    return <main>
        <UserInfo username={username} />

        <Suspense fallback={<PostListSkeleton />}>
            <UserPostList username={username} />
        </Suspense>
    </main>
}

// 워터폴은 여러 컴포넌트를 동시에 평가함으로써 방지됩니다.

async function UserInfo({ username }) {
    const user = await fetchUserInfo(username);
    return <>
        <h1>{user.displayName}</h1>
        {user.bio ? <Markdown content={user.bio} /> : ""}
    </>
}

async function UserPostList({ username }) {
    const posts = await fetchUserPostList(username);
    return /* post list ui omitted for brevity */;
}

리액트 자체의 40kB gzip 압축 번들을 제외하면, 위 예시는 UI와 데이터 페칭을 위한 자바스크립트가 전혀 없습니다. 단순히 마크업을 스트리밍할 뿐이죠! 예를 들어, <Markdown /> 컴포넌트 내부의 가상 마크다운 파서는 백엔드에 그대로 남아 있습니다. 인터랙티브한 프론트엔드가 필요할 때는, "use client"로 시작하는 파일에 컴포넌트를 배치하여 클라이언트 컴포넌트를 만들 수 있습니다.

"use client"; // 이 주석은 파일이 클라이언트 사이드로 번들링 되도록 마킹합니다.

export function CopyButton({ url }) {
    return <>
        <span>{url}</span>
        <button onClick={() => {
            const full = new URL(url, location.href);
            navigator.clipboard.writeText(full.href);
            // 에러 처리나 성공시 보여주는 ui는 제외했습니다
        }}>copy</button>
    </>
}

export function Card() {
    return <article>
        <header>
            {/* 브라우저가 CopyButton을 import 하도록 합니다 */}
            <CopyButton url="/q+a/2506010139" />
        </header>
        <p>
            {/* 마크다운 처리는 백엔드에서 수행됩니다 */}
            <Markdown content=".........." />
        </p>
    </article>
}

§실제로 발생하는 앱 라우터의 문제점들

런타임 엔지니어로 근무하던 Bun을 그만둔 후(서버 컴포넌트 번들링과 RSC 템플릿을 구현했습니다), 저는 최전선에서 일하는 소규모 회사에 합류했습니다. Hono 백엔드를 가진 Next.js 애플리케이션이었습니다. 다음 내용들은 실제 현장에서 유지보수 및 신규 기능 개발 시 마주친 문제들을 단순화한 것입니다. 이 모든 것들의 결과로 인해, 모두가 설계상의 결함을 우회하거나, 당연히 해결되어야 할 문제가 왜 해결 불가능한 장애물이 되었는지 서로 설명하는 데 시간을 낭비하게 되었습니다.

§낙관적 업데이트는 불가능합니다

Next.js 문서에는 변경 수행 시 낙관적 업데이트에 대한 언급이 없습니다. 이 경우를 고려하지 않은 것으로 보입니다. 리액트 서버에서 렌더링되는 컴포넌트는 설계상 마운팅 후 수정할 수 없습니다. 변경될 수 있는 요소는 클라이언트 컴포넌트 내에 있어야 하지만, 백엔드에서 SSR(서버 측 렌더링) 중에도 클라이언트 컴포넌트에서 데이터 가져오기가 불가능합니다. 이로 인해 데이터 가져오기만 수행하는 어색하게 작은 서버 컴포넌트와, 대부분 정적인 버전의 페이지를 포함하는 클라이언트 컴포넌트가 분리되어 있는 구조가 됩니다.

export default async function Page() {
    const user = await fetchUserInfo(username);
    return <ProfileLayout>
        <UserProfile user={user} />
    </ProfileLayout>;
}

"use client"; // 클라이언트 코드를 반드시 두 번째 파일로 분리해야 합니다!

export function UserProfile({ user: initialUser }) {
    // 훌륭한 상태 관리 라이브러리들이 많이 존재합니다.
    // 단순화를 위해 이 예제에서는 하나의 상태 셀을 사용하겠습니다.
    const [user, optimisticUpdateUser] = useState(initialUser);

    async function onEdit(newUser) {
        optimisticUpdateUser(newUser);
        const resp = await fetch("...", {
            method: 'POST',
            body: JSON.stringify(newUser),
            ... // (헤더, 자격 증명, 추적 등)
        })
        if (!resp.ok) /* 항상 오류 검사를 잊지 마세요! */
    }

    return <main>{/* 편집 가능한 필드가 있는 사용자 인터페이스... */}</main>:
}

페이지의 상호작용 요소가 늘어날수록 정적 부분을 서버 측에서 완전히 처리하기 복잡해집니다. 업무용 앱에서는 거의 모든 UI 요소가 동적 데이터를 표시합니다. WebSocket은 데이터가 업데이트될 때 실시간으로 동기화합니다(예: 사용자 카드의 온라인 상태와 기본 프로필 정보). 이러한 컴포넌트 설정은 엔지니어가 이해하고 유지하기 어렵기 때문에, 거의 모든 페이지가 데이터 가져오기를 정의하는 page.tsx를 통해 완전히 "use client 방식으로 구현됩니다.

직장에서 사용하는 데이터 페칭 라이브러리인 TanStack Query를 통해 실제 적용 사례를 보다 구체적으로 살펴보겠습니다.

// 작업 시 타입 안전성을 위해 `defineQuery` 헬퍼 함수가 사용됩니다.
// 페처는 단순하며 백엔드나 프론트엔드에서 실행될 수 있습니다.
export const queryUserInfo = (username) => ({
    queryKey: ['user', username],
    queryFn: async ({ ... }) => /* fetch data */
});

export default async function Page({ params }) {
    const { username } = await params; 

    // 리액트 서버에는 글로벌 상태가 없습니다.
    // 레이아웃이 병렬로 실행되기 때문에 TanStack `QueryClient`는 경로 마다 여러 번 재구성되어야 합니다.
    const queryClient = new QueryClient();
    await queryClient.ensureQueryData(queryUserInfo(username));

    // HydrationBoundary는 리액트 서버에서 클라이언트 컴포넌트로
    // JSON 데이터를 전달하는 클라이언트 컴포넌트입니다.
    return <HydrationBoundary state={dehydrate(queryClient)}>
        <ClientPage />
    </HydrationBoundary>;
}

"use client";
export function ClientPage() {
    const { username } = useParams();
    const { data: user } = useSuspenseQuery(queryUserInfo(username));

    // ... 이외의 다른 훅들 

    return <main>
        {/* ... 인터랙티브 웹 페이지 */}
    </main>;
}

이 예제는 서버 컴포넌트 번들링 규칙 때문에 반드시 세 개의 별도 파일로 구성되어야 합니다. (클라이언트 컴포넌트는 "use client"가 필요하며, 서버 전용 임포트 때문에 서버 컴포넌트 파일은 클라이언트에서 종종 임포트할 수 없습니다.) Pages 라우터에서는 getStaticProps와 getServerSideProps가 트리 셰이킹을 지원하기 때문에 단일 파일로 구현할 수 있었습니다.

§모든 탐색(navigation)은 또 다른 페치 요청입니다

앱 라우터는 모든 페이지를 서버 컴포넌트로 시작하며 이상적으로는 상호작용 영역이 작기 때문에, 새 페이지로 이동할 때는 클라이언트가 이미 보유한 데이터와 무관하게 Next.js 서버를 다시 호출해야 합니다! loading.tsx 파일이 있더라도, /를 열고 /other로 이동한 후 다시 /로 돌아오면 홈페이지를 재로딩하는 동안 로딩 상태가 표시됩니다.

이 방법이 통하는 유일한 경우는 완벽히 정적인 콘텐츠일 때로, 이때는 즉각적인 탐색과 사전 로딩이 훌륭하게 작동합니다. 하지만 웹 애플리케이션은 정적이지 않고 다량의 동적 콘텐츠를 포함합니다. 클라이언트가 페이지를 즉시 표시하는 데 필요한 모든 것을 이미 가지고 있음에도 불구하고, 로그인 상태가 홈페이지를 변경시키는 것은 정말 짜증나는 일입니다. 쿠키가 변경된 것도 아닌데 말이죠.

참고: 빈 프로젝트에서 추가 테스트를 진행한 결과, Next 프론트엔드 코드가 실제 콘텐츠 없이 경로를 미리 가져오는 사례를 관찰했습니다. 'Hello World' 예제에서는 1.8kB 크기의 RSC 페이로드가 2개의 서로 다른 JS 청크를 4번에 걸쳐 가리켰습니다. 이는 순전히 대역폭과 아웃바운드 트래픽을 낭비하는 행위입니다. 특히 링크를 실제로 클릭할 때 이 모든 정보를 다시 가져온다는 점을 고려하면 더욱 그렇습니다.

1:"$Sreact.fragment"
2:I[39756,["/_next/static/chunks/ff1a16fafef87110.js","/_next/static/chunks/7dd66bdf8a7e5707.js"],"default"]
3:I[37457,["/_next/static/chunks/ff1a16fafef87110.js","/_next/static/chunks/7dd66bdf8a7e5707.js"],"default"]
4:I[97367,["/_next/static/chunks/ff1a16fafef87110.js","/_next/static/chunks/7dd66bdf8a7e5707.js"],"ViewportBoundary"]
6:I[97367,["/_next/static/chunks/ff1a16fafef87110.js","/_next/static/chunks/7dd66bdf8a7e5707.js"],"MetadataBoundary"]
7:"$Sreact.suspense"
0:{"b":"TdwnOXsfOJapNex_HjHGt","f":[["children","other",["other",{"children":["__PAGE__",{}]}],["other",["$","$1","c",{"children":[null,["$","$L2",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L3",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","forbidden":"$undefined","unauthorized":"$undefined"}]]}],{"children":null},[["$","div","l",{"children":"loading..."}],[],[]],false],["$","$1","h",{"children":[null,["$","$1","KCFxAJdIDH3BlYXAHsbcVv",{"children":[["$","$L4",null,{"children":"$L5"}],["$","meta",null,{"name":"next-size-adjust","content":""}]]}],["$","$L6","KCFxAJdIDH3BlYXAHsbcVm",{"children":["$","div",null,{"hidden":true,"children":["$","$7",null,{"fallback":null,"children":"$L8"}]}]}]]}],false]],"S":false}
5:[["$","meta","0",{"charSet":"utf-8"}],["$","meta","1",{"name":"viewport","content":"width=device-width, initial-scale=1"}]]
9:I[27201,["/_next/static/chunks/ff1a16fafef87110.js","/_next/static/chunks/7dd66bdf8a7e5707.js"],"IconMark"]
8:[["$","title","0",{"children":"Create Next App"}],["$","meta","1",{"name":"description","content":"Generated by create next app"}],["$","link","2",{"rel":"icon","href":"/favicon.ico?favicon.0b3bf435.ico","sizes":"256x256","type":"image/x-icon"}],["$","$L9","3",{}]]

검토해 보니 여기에 실제로 일부 내용이 있더군요. 로딩 상태입니다. 보이시나요?

["$","div","l",{"children":"loading..."}]

이 모든 데이터가 실제 페이지 RSC에서 다시 전송되기 때문에 여전히 큰 낭비입니다.

이 문제의 해결책으로 보이는 staleTime은 실험적 기능으로 분류되어 "실제 운영 환경에서는 권장되지 않는다"고 명시되어 있습니다. 이 기능이 비기본 설정의 추가 구성 옵션으로 처리되고 있다는 사실 자체가 당혹스럽습니다. 설령 이를 사용한다고 해도, 동일한 기본 데이터를 참조하는 여러 페이지 간에 데이터를 공유하는 것은 불가능합니다.

앱 라우터로는 표현할 수 없는 로딩 상태의 한 형태는, 예를 들어 Git 프로젝트의 이슈 페이지와 같은 페이지에서 사용자 이름을 클릭해 해당 프로필 페이지로 이동하는 경우입니다. loading.tsx를 사용하면 전체 페이지가 스켈레톤 형태로 표시되지만, TanStack Query로 이러한 쿼리를 모델링하면 사용자 정보와 저장소를 불러오는 동안 사용자 이름과 아바타를 즉시 표시할 수 있습니다. 서버 컴포넌트는 렌더링된 컴포넌트에서만 데이터가 사용 가능하기 때문에 이 형태의 탐색을 지원하지 않습니다. 따라서 데이터를 다시 가져와야 합니다.

우리 Next.js 사이트의 서버 컴포넌트 데이터 페처에는 데이터 페치 단계를 완전히 건너뛰어 소프트 네비게이션을 더 빠르게 만들기 위한 코드 라인이 있습니다.

export function serverSidePrefetchQueries(queries) {
    if ((await headers()).get("next-url")) {
        // 이건 소프트 네비게이션입니다. 더 빠르게 하려면 프리페칭을 건너뛰세요.
        // 클라이언트가 이미 이 데이터를 가지고 있을 수 있으며, 그렇지 않더라도 로딩 상태를 가지고 있습니다.
        // 이상적으로는 이 서버 요청은 없어야 합니다. 앱의 대부분이 클라이언트 컴포넌트로 작성되어
        // 거의 모든 코드가 클라이언트 측에 있기 때문이죠. 솔직히 말해서 앱 라우터의 설계상의 결함이라고 할 수 있죠.
        return;
    }
    // ... 데이터 프리 페칭 로직 ...
}

또한 loading.tsx에는 useQuery 호출이 포함되어야 합니다. 이렇게 하면 빈 RSC에 대한 네트워크 요청이 발생하는 동안 실제로 필요한 경우 데이터를 가져올 수 있습니다. 실제로 loading.tsx의 상태는 실제 클라이언트 컴포넌트 자체일 수 있으며, 그러면 클라이언트 페이지가 표시됩니다.

"use client";
export default function PageLoadingSkeleton() {
    return <ClientPage />;
}

업무에서는 단순히 loading.tsx 파일에 useQuery 호출을 포함하고 스켈레톤만 표시하도록 만듭니다. Next.js가 실제 서버 컴포넌트를 로드할 때면 어쨌든 페이지 전체가 재마운트되기 때문입니다. 여기서는 VDOM 비교가 발생하지 않으므로, 요청 완료 후 모든 훅(useState)이 약간의 지연후에 초기화됩니다. 기존 DOM만 업데이트하고 상태를 유지하도록 Next.js에 간청하는 간단한 사례를 재현해 보려 했지만, 그렇게 되지 않았습니다. 다행히 빈 RSC 호출에 소요되는 시간은 충분히 짧습니다.

§레이아웃은 인위적으로 제한됩니다

레이아웃은 데이터를 가져올 수는 있지만, 요청을 어떤 방식으로든 관찰하거나 변경할 수 없습니다. 이는 Next.js가 원하는 때에 레이아웃을 가져오고 캐시할 수 있도록 하기 위함입니다. 다른 모든 프레임워크에서는 레이아웃이 단순히 일반 컴포넌트일 뿐이며 페이지 컴포넌트와 기능상 차이는 없습니다.

레이아웃을 개별적으로 로드하는 아이디어는 매력적이지만 이는 결국 모든 데이터 로드 작업이 레이아웃마다 재실행되어야 한다는 의미라서 어리석은 선택이 됩니다. QueryClient를 공유할 수 없습니다. 대신, 그들이 약속한 것처럼 동일한 GET 요청을 캐싱하려면 몽키 패치된 fetch 메서드에 의존해야 합니다.

동료가 Next.js가 왜 특정 코드를 거부하는지 묻는다면, 기술적 복잡성을 설명하는 건 포기하고 그냥 "Next.js 기술 문제야, 곧 해결할 테니까 걱정 마"라고 말하곤 합니다. 이 규칙들은 일반 개발자들이 이해하기엔 너무 까다롭습니다.

§여전히 모든 콘텐츠를 두 번 다운로드합니다

"아일랜드 아키텍처"와 달리 서버 컴포넌트는 Suspense 지원 및 클라이언트 컴포넌트 상태 보존을 위해 프론트엔드에서 여전히 하이드레이션되어야 합니다. 소프트 네비게이션 시 "RSC 페이로드"(HTML이 전혀 아님)는 fetch로 가져옵니다. 새로 고침 시 첫 번째 페인트에는 HTML이 필요하지만, 클라이언트 컴포넌트와 Suspense 관련 정보는 해당 HTML에 포함되어 있지 않습니다. 리액트의 해결책은 전체 페이지 마크업의 두 번째 사본을 전송하는 것입니다. Next.js 프로덕션 서버가 동적 페이지 렌더링 시 전송하는 예시는 다음과 같습니다.

<!DOCTYPE html>
<html>
<head>
    {link and meta tags}
</head>
<body>
    {server side render}
    <script>
        // 글로벌 `__next_f`를 배열로 설정하는 부트스트랩 스크립트.
        // 리액트가 로드되면 이 `.push` 함수가 재정의되어
        // 새로운 청크를 RSC 디코더에 직접 기록합니다.
        // 이 스크립트에는 DOM 헬퍼도 포함되어 있습니다.
        (self.__next_f=self.__next_f||[]).push([0])
    </script>
    <script>
        // 애플리케이션 셸용 RSC 페이로드.
        self.__next_f.push([1,"1:\"$Sreact.fragment\"\n2:I[658993,[\"/_next/st{...}"])
    </script>

    <!--
        닫는 태그 </body>는 아직 작성되지 않았습니다.
        해결되지 않은 서스펜스 경계가 존재하기 때문입니다.
        시간이 흐른 후에야 추가 데이터가 작성됩니다.
    -->
    <div class="user-post-list">
        {server side render of a Suspense boundary}
    </div>
    <script>
        // 서스펜스 경계에 대한 RSC 페이로드
        self.__next_f.push([2,"14:[\"$\",\"div\",null,{\"children\":[[\"$\",\"h4\"{...}"])
    </script>
    
    <!-- HTML 및 스크립트 태그는 페이지 전체가 완료될 때까지 반복됩니다 -->
</body>
</html>

이 솔루션은 초기 HTML 페이로드의 크기를 두 배로 늘립니다. 하지만 더 나쁜 점은 RSC 페이로드에 JS 문자열 리터럴로 감싸져 있는 JSON이 포함되어 있다는 것입니다. 이는 HTML보다 훨씬 비효율적인 형식입니다. 브로틀리(brotli)로 잘 압축되고 브라우저에서 빠르게 렌더링되는 것처럼 보이지만, 이는 낭비입니다. 하이드레이션 패턴을 사용하면 최소한 로컬 데이터는 상호작용 및 다른 페이지에서 재사용될 수 있습니다.

상호작용이 거의 없거나 전혀 없는 페이지에서도 비용을 지불하게 됩니다. Next.js 문서를 예로 들면, 홈페이지 로딩 시 약 750kB(HTML 250kB와 스크립트 태그 500kB)의 페이지가 로드되며, 콘텐츠가 두 번 포함됩니다.

Mac에서는 Cmd + Opt + u를, 다른 플랫폼에서는 Ctrl + u를 눌러 확인할 수 있습니다. 그런 다음 Cmd / Ctrl + f를 눌러 블로그의 특정 문자열(예: "풀스택 웹 애플리케이션 구축")을 찾아보세요. 두 번 등장합니다. 이는 리액트 서버 컴포넌트의 핵심 요소이므로 피할 수 없습니다.

이런 RSC 형식은 분명히 더 많은 낭비를 낳습니다. 하지만 정말로 /_next/static/chunks/6192a3719cda7dcc.js라는 문자열이 27번이나 따로따로 나타나는 이유를 캐내고 싶진 않네요. 뭐야, 너희들. 대역폭이 공짜냐???

§터보팩은 구립니다

이 섹션은 건설적이지 않습니다.

• 터보팩은 빠르지 않습니다
• 터보팩은 디버거에서 디버깅하기 어려운 코드를 생성합니다(개발 모드에서)
• 터보팩은 많은 경우에 불명확한 오류 메시지를 출력합니다

평소라면 이 점을 블로그에 별도 섹션으로 다루지 않았겠지만, 프로젝트에서 직접 가져온 세 가지 실제 사례를 지적하고자 합니다.

첫 번째는 서버/클라이언트 컴포넌트 모델을 충족시키기 위한 리팩토링 과정에서 실수로 클라이언트 컴포넌트를 async로 만든 경우입니다. 이 문제는 문제가 발생한 위치를 전혀 알려주지 않고 서버 스택 트레이스만 포함하고 있어서 상당히 성가셨습니다.

끔찍한 오류 메시지의 또 다른 사례입니다.

이 두 번째 오류의 근본적인 문제(기억나지 않음)를 수정한 후, 개발 서버가 멈춰서 복구하기 위해 재시작해야 했습니다.

마지막으로, 디버거 중단점을 수십 번 설정할 때마다 변수 이름 hello가 __TURBOPACK__imported__module__$5b$project$5d2f$client$2f$src$2f$utils$2f$filename$2e$ts__$5b$app$2d$client$5d$__$28$ecmascript$29$__["hello"] 같은 거지같은 이름으로 바뀌는 경우입니다.

네. 이 모든게 구립니다. 어쩌면 좋을까요?

§업무에서 Next.js와 Vercel을 매끄럽게 대체하기

웹 프로젝트에는 두 가지 유형이 있습니다.

• 주로 정적 콘텐츠로 구성된 웹사이트
• 주로 동적이고 상호작용적인 컴포넌트를 가진 웹 애플리케이션

Next.js는 이 두 가지 작업 모두에 적합하지 않은 도구입니다. 정적 웹사이트를 만드는 첫 번째 유형에 해당한다면 Astro나 Fresh를 선택하세요. 리액트의 모든 기능을 필요로 하는 분들을 위해, 이 섹션에서는 벤더에 종속된 Next를 TanStack Start로 점진적으로 매끄럽게 교체한 방법을 설명합니다.

이 Vite 설정부터 시작했습니다.

const config = defineConfig(({ mode }) => {
    const env = loadEnv(mode, process.cwd(), "NEXT_PUBLIC_");
    return {
        // Next.js 기본 포트 3000을 사용하세요
        server: { port: 3000 },
        // Next.js의 기본 환경 접두사 "NEXT_PUBLIC_"을 사용하십시오.
        define: Object.fromEntries(Object.entries(env).map(
            ([k, v]) => [`process.env.${k}`, JSON.stringify(v)])),
        plugins: [
            viteTsConfigPaths({ projects: ["./tsconfig.json"] }),
            tailwindcss(),
            // 동료들이 이해하기 쉽도록 `src/tanstack-routes`에 있는 라우트를
            // 포팅하기 시작했습니다. 마이그레이션이 완료되면
            // 기본 `src/routes`로 되돌아갈 예정입니다.
            tanstackStart({
                router: { routesDirectory: "src/tanstack-routes" },
            }),
            viteReact(),
        ],
        resolve: {
            // 증분 마이그레이션의 핵심: `next`를 다른 곳으로 리디렉션
            alias: { next: path.resolve("./src/tanstack-next/") },
            conditions: ["tanstack"],
            extensions: [
                // `utils/session.tanstack.ts`와 같은 이름의 파일이
                // `utils/session.ts`를 가져올 때 덮어쓸 수 있도록 허용합니다.
                ".tanstack.tsx", ".tanstack.ts",
                // 기본 임포트 확장자
                ".mjs", ".js", ".mts", ".ts",
                ".jsx", ".tsx", ".json",
            ],
        },
    };
});

그런 다음 Next.js API의 모든 사용처를 찾아 제거하거나 TanStack용 스텁을 만들었습니다. 예를 들어, src/tanstack-next/link.tsx는 next/link를 구현합니다.

import { Link } from "@tanstack/react-router";
import type { LinkProps } from "next/link";

export default function LinkAdapter({ href, ...rest }: LinkProps) {
  return <Link {...rest} to={href as unknown as any} />;
}

이러한 스텁 중 일부는 매우 간단할 수 있습니다. 처음 시작했을 때, 제가 구현한 useRouter는 단순히 return {}였지만, 나중에 객체에 몇 가지 메서드를 추가해야 했습니다. 여기 코드 자체는 임시적인 것이므로 깔끔할 필요가 없습니다.

이제 새 사이트는 필요한 Next.js API를 스터빙하거나 .tanstack.ts 확장자를 사용해 파일별로 로직을 재구현함으로써 거의 모든 클라이언트 컴포넌트를 가져올 수 있습니다. 그리고 얼마 지나지 않아 TanStack Start에서 사이트 홈페이지를 작동시키는 데 성공했고, 해당 브랜치를 병합했습니다.

이 첫 번째 PR은 우리 페이지 중 하나만을 지원했으며, 추가된 코드 천 줄과 삭제된 코드 40줄로 이를 수행할 수 있었습니다. 저는 이전 패치를 통해 next/image 및 next/font의 몇 가지 사용 사례를 제거한 적이 있습니다.

남은 작업은 다른 모든 경로를 포팅하는 것이었습니다. Next.js에서 다른 프레임워크로 마이그레이션할 때 잃게 되는 한 가지는 UI에서 데이터 페칭 함수를 await할 수 있는 기능입니다. 실제로 모든 경로를 loader 함수로 이동시키면 페이지가 서버 측 렌더링(SSR)될 때 어떤 일이 발생하는지 훨씬 명확해졌습니다. 여러 번의 데이터 가져오기가 필요한 페이지의 경우, 해당 페이지에 필요한 모든 관련 데이터를 반환하는 단일 특수 API 호출로 통합할 수 있었습니다.

다시 한번 강조하자면, 서버 컴포넌트에서의 마이그레이션 경로는 단순히 코드를 단순화하는 것입니다. RSC는 본질적으로 필요 없는 것들로 가득한 혼란스러운 길로 이끌어갑니다. 우리 사이트의 거의 모든 복잡한 부분이 모든 엔지니어에게 이해하기 쉬워졌습니다. 유일한 예외는 모두가 새로운 파일 시스템 라우팅 규칙에 익숙해져야 했던 점입니다. 충분한 예시를 통해 우리 모두 그 요령을 터득했습니다.

증분 마이그레이션을 통해 신규 코드가 기존 배포를 방해하지 않았습니다. TanStack이 점진적으로 코드베이스를 인수하면서, 결국 모든 Next.js 스텁을 삭제하고 TanStack 라우터가 제공하는 모든 우수한 타입 안전성 기능을 확보했습니다. 최종적으로 사이트는 모든 측면에서 더 빠른 성능을 보였습니다: 개발 모드, 프로덕션 페이지 로딩 시간, 소프트 네비게이션, 그리고 Vercel을 사용한 Next 배포보다 저렴한 비용으로 구현되었습니다.

변화를 목격하는 건 우리만이 아닙니다. 저는 소셜 미디어를 멀리하려 노력하지만, 누군가 브라이언 앵글린(Brian Anglin)이 Superwall에서 진행한 작업 결과를 보내왔는데, TanStack Start에서 CPU 사용량이 엄청나게 감소한 걸 보여주더군요. 또한 1년 전 ChatGPT가 Next.js에서 Remix로 전환한 일도 기억납니다(관련 온라인 대화: [1] [2] [3]).

§next/metadata는 훌륭합니다

제 생각에 이건 Next.js가 가진 몇 안 되는 좋은 API 중 하나이며, TanStack으로 전환하면서 코드에서 유일하게 작업이 더 어려워진 부분이었습니다. 코드를 악화시키기보다는, 그냥 그들의 메타데이터 API를 일반 함수로 포팅해서 누구나 사용할 수 있게 했습니다. 원래는 NPM에 1:1 포팅 버전을 올렸지만, 올해 초에 API를 간결하고 이해하기 쉬운 하나의 파일로 단순화했습니다. 이 블로그 글 작성 시점 기준으로, TanStack 호환 meta.toTags API를 추가했으며, JSR이나 NPM에서 설치하거나 단순히 프로젝트에 복사해서 사용할 수 있습니다.

공지: 본 글 작성에 시간이 부족하여 라이브러리는 아직 업데이트되지 않았습니다. 아마도 ~~이번 주 말(10월 24일)~~ 가까운 시일 내에 처리할 예정입니다... 임시로 업무용으로 사용 중인 버전을 제 웹사이트에 공유합니다. meta.tanstack.ts

// 프로젝트에 한 번만
import * as meta from "@clo/lib/meta.ts";

export const defineHead = meta.toTags.bind(null, {
    // 사이트 전체 옵션
    base: new URL("https://paperclover.net"),
    titleTemplate: (title) => [title, "paper clover"]
        .filter(Boolean).join(' | '),
    // ...
});

// 각 페이지마다...
export const Route = createFileRoute("/blog")({
    head: () =>
        defineHead({
            title: "clover's blog", // `titleTemplate`으로 템플릿 처리됨
            description: "a catgirl meows about her technology viewpoints",
            canonical: "/blog", // `base`와 결합됨

            // 지정 시, 페이지 제목과 설명을 기본값으로 사용하여
            // Open Graph 및 Twitter 임베드를 구성합니다.
            // 기본값도 괜찮지만, 더 많은 옵션을 지원합니다.
            embed: {
                image: "/img/blog.webp",
            }, 

            // 모든 특수 메타 태그는 JSX 프래그먼트로 처리됩니다.
            // 이는 리액트 렌더링하지 않고 단순히 태그를 순회합니다.
            // 제 목표는 가장 흔한 99%의 사용 사례를 커버하는 것이었습니다.
            extra: <>
                <meta name="site-verification" content="waffles" />,
            </>,
        }),

    component: Page,
});

function Page() {
    ...
}

제 버전은 Next.js 메타데이터 객체의 전체 영역을 커버하는 데 초점을 두지 않았으며, 대신 인라인 JSX를 사용하여 그 공백을 메웠습니다.

§next/og 또한 좋습니다

특별한 의견은 없습니다. 그냥 @vercel/og 패키지가 있다는 점을 모두에게 상기시키고 싶을 뿐입니다.

§제 경험은 일반적인 것 같아요

Next.js Conf 2024에서 참석자 모두가 서버 컴포넌트(Server Components)에 열광했습니다. 정확히 누구와 이야기했는지는 기억나지 않지만, 주요 인사들은 모두 이 기술에 주목하고 있었습니다. RSC의 번들러 부분을 구현한 저는 이 포맷의 몇 가지 문제점을 목격했습니다. Next 15가 지난해 App Router를 "안정화"하면서 많은 기업들이 이를 기반으로 제품을 구축하고 있으며, 이러한 문제점들을 직접 경험하고 있습니다.

저는 Next.js를 늦게 접하게 되어 6월에야 버전 15로 시작했습니다. 하지만 행사에서 만난 모든 분들이 제 의견에 공감해 주셨습니다. Bun의 1.3 파티에서 이 주제로 이야기한 분들도 모두 동의하셨죠. 심지어 Vercel의 몇몇 분들조차 Next.js의 실제 사용 방식이 마음에 들지 않는다고 말씀하셨습니다.

TanStack Start가 안정화되면서 모두가 원하는 Next.js 대체 솔루션이 되길 바랍니다.

§사용자를 존중하는 도구를 선택하세요

자바스크립트 생태계는 상당 부분 엉망이고, 그 때문인지 웹 개발은 종종 조롱의 대상이 됩니다.. 저는 웹 작업을 회복 불가능한 난장판이라고 생각했던 적이 수없이 많았지만, 그 혼란은 사실 제가 둘러싸고 있던 흔히 쓰이는 라이브러리들 때문이었습니다. 그 껍질을 벗겨내면 현대 웹 개발 기술은 정말 대단합니다.

2024년 말부터 프레임워크 없이 이 웹사이트를 처음부터 직접 제작해 왔습니다. 자체 개발한 TUI 진행률 위젯, 정적 파일 프록시, 증분 빌드 시스템 등 다양한 컴포넌트를 직접 구현하며 작업했습니다. 지난 수년간 가장 행복한 코딩 경험이었습니다. 페이퍼 클로버 방문자들은 더 나은 품질의 웹사이트를 이용하게 되고, 제가 만든 미니 라이브러리는 공개적으로 활용될 수 있게 추출됩니다. 덕분에 모두가 이득을 보게 되었죠.

이 정도로 완전히 처음부터 시작하는 방식은 대부분의 사람들에게, 특히 직장에서는 부담스럽습니다. 최소한 우리를 존중하는 고품질 도구에만 우리의 관심과 돈을 쏟아야 한다고 생각합니다. 그리고 Next.js와 그 배후 기업인 Vercel은 그렇지 않습니다.

Next.js를 사용하면서 개발자로서 존중받는다는 느낌이 들지 않는다면, 과연 여러분과 동료들이 그들의 [서버리스 제국]을 계속 지지하고 싶은지 고민해 보세요. 현재 Vite 생태계는 구축하기에 꽤 괜찮아 보이지만, 아직 대규모 프로덕션 환경에서 그들의 도구를 사용해 본 경험은 거의 없습니다. Void0의 Vite+ 출시 소식은 흥미롭지만, 이러한 벤처 수준의 지원 도구가 장기적으로 우리(최종 사용자와 개발자)를 존중할지는 시간이 지나야 알 수 있을 것입니다.

Next.js Conf 2025는 글을 쓰는 시점 기준으로 내일입니다. 800달러짜리 티켓을 구매하는 대신, 웹 개발 생태계를 존중하고 개선하는 TanStack 팀에 그 돈을 기부하기로 결정했습니다.

앞으로의 계획

점진적으로, 저는 저를 존중하지 않는 많은 소프트웨어들을 더 나은 대안으로 교체해 왔습니다. 그 예로는 GitHub, Visual Studio Code, DaVinci Resolve, Discord, Google Drive/Workspace 등이 있으며, 그 외에도 많습니다. 이 블로그에서는 제가 진행 중인 기술적 작업들(프로그레스 라이브러리, 자체 사이트 생성기의 목적, 현재 직장에서의 배움)과 Bun에서의 과거 프로젝트들(HMR, 크래시 리포터, 내장 모듈 번들링을 위한 독특한 시스템에 대한 세부 사항)에 대해 더 많이 다루려 합니다. 관심이 있으시다면 이메일 리스트에 가입해 주세요.

click here to send an email to subscribe@paperclover.net, requesting that you would like to be added to the mailing list. (i manage this mailing list manually)

↑ — ask a question about this article (English)