최근 개발자 커뮤니티에서 Next.js의 대안을 찾는 움직임이 그 어느 때보다 활발하게 일어나고 있는데요.

유명 테크 유튜버인 ‘Cosden Codes’가 자신의 플랫폼인 ‘Cosden Codes’를 Next.js에서 TanStack Start로 전격 이주시킨 경험담을 공유하며 큰 화제를 모았습니다.

Youtube Link

그는 왜 익숙하고 강력한 Next.js를 뒤로하고 아직 정식 버전도 출시되지 않은 새로운 프레임워크를 선택했는지 그 구체적인 이유가 궁금해지는데요.

이번 글에서는 그의 영상을 바탕으로 두 기술 스택의 근본적인 철학 차이와 실제 마이그레이션 과정에서 마주한 현실적인 장단점들을 깊이 있게 파헤쳐보려 합니다.

프레임워크의 근본적인 철학 차이

두 프레임워크를 비교할 때 가장 먼저 짚고 넘어가야 할 점은 설계의 출발점이 완전히 다르다는 사실인데요.

Next.js는 철저하게 ‘서버 우선’ 철학을 바탕으로 모든 컴포넌트가 기본적으로 서버에서 동작하도록 설계되어 있습니다.

이는 서버 리소스를 직접 활용하고 초기 렌더링 속도를 높이는 데 최적화되어 있지만 클라이언트 기능을 쓰려면 ‘use client’라는 선언이 필수적입니다.

반면 TanStack Start는 ‘클라이언트 우선’ 접근 방식을 취하며 필요한 경우에만 서버 기능을 점진적으로 도입하는 구조를 가지고 있거든요.

사용자와의 복잡한 상호작용이 많은 현대적인 웹 앱에서는 이러한 클라이언트 중심의 유연함이 때로는 더 큰 강력함을 발휘하기도 합니다.

로더와 서버 함수의 이형적 매력

TanStack Start의 핵심은 내비게이션 라이브러리인 ‘TanStack Router’와 긴밀하게 결합된 ’loader’ 함수에 있는데요.

이 로더 함수는 초기 접속 시에는 서버에서 실행되어 HTML을 생성하고 이후 페이지 이동 시에는 클라이언트에서 실행되는 독특한 특성을 가집니다.

Cosden Codes는 이러한 구조가 데이터 페칭 로직을 한 곳에서 관리하면서도 환경에 따라 최적으로 동작하게 만든다는 점에 주목했습니다.

여기에 더해 ‘create server function’이라는 강력한 도구가 서버와 클라이언트의 경계를 마법처럼 허물어주거든요.

이 함수는 서버에서 실행될 때는 데이터베이스에 직접 접근하지만 클라이언트에서 호출될 때는 자동으로 ‘RPC(Remote Procedure Call)‘로 변환되어 통신합니다.

개발자는 내부적으로 이것이 API 요청인지 단순한 함수 호출인지 일일이 신경 쓰지 않아도 된다는 뜻입니다.

리액트 쿼리와의 환상적인 하모니

Cosden Codes가 이번 이주를 결심하게 된 가장 결정적인 배경 중 하나는 바로 ‘React Query’와의 통합 수준 때문이었는데요.

Next.js 환경에서 리액트 쿼리를 사용하려면 서버에서 페칭한 데이터를 하이드레이션하기 위해 수동으로 복잡한 설정을 거쳐야만 합니다.

하지만 TanStack Start는 같은 생태계의 도구답게 서버의 쿼리 캐시 상태를 클라이언트로 전송하는 과정을 완전히 자동화해주거든요.

서버에서 이미 채워진 캐시가 클라이언트로 넘어올 때 아무런 추가 작업 없이 그대로 이어지는 경험은 개발자에게 엄청난 해방감을 선사합니다.

특히 데이터 수정 작업인 ‘Mutation’을 처리할 때 리액트 쿼리의 캐시 무효화 전략을 그대로 쓸 수 있다는 점은 복잡한 상태 관리를 비약적으로 단순화해줍니다.

캐싱에 대한 전혀 다른 접근 방식

캐싱 전략에 있어서도 두 프레임워크는 서로 가는 길이 완전히 다르다는 점을 명확히 인지해야 하는데요.

Next.js는 서버 레벨에서 데이터를 캐싱하여 여러 사용자에게 공유하는 ‘서버 중심 캐시’를 매우 강조하는 편입니다.

반면 TanStack Start는 표준 HTTP 헤더를 활용하여 브라우저나 ‘CDN’ 레벨에서 캐싱을 제어하는 정석적인 방식을 따르고 있거든요.

이는 특정 서버 환경에 종속되지 않고 어떤 네트워크 인프라에서도 유연하게 동작할 수 있다는 기술적 자유도를 제공합니다.

Cosden Codes는 자신의 서비스 특성상 서버의 직접적인 통제보다 표준 규격을 따르는 캐싱 방식이 더 관리하기 편했다고 설명합니다.

마이그레이션 과정에서 마주한 현실적인 그림자

물론 모든 과정이 완벽했던 것은 아니며 Cosden Codes는 이주 과정에서 겪은 솔직한 고충들도 털어놓았는데요.

가장 큰 장벽은 Next.js와 비교했을 때 턱없이 부족한 ‘문서화의 품질’과 예제 코드의 부재였습니다.

문제가 발생했을 때 공식 문서를 뒤지기보다는 ‘Discord’ 채널에 들어가 다른 개발자들의 질문을 검색해야 하는 경우가 허다했거든요.

아직 정식 출시 전인 ‘Release Candidate’ 단계이다 보니 예상치 못한 버그들이 발목을 잡는 경우도 종종 발생했습니다.

특히 서버 함수 내에서 복잡한 유니온 타입을 반환할 때 타입 추론이 깨지는 현상은 실무에서 꽤나 골치 아픈 문제로 다가왔습니다.

그는 이러한 문제들을 해결하기 위해 타입스크립트의 ‘any’를 남발하거나 특정 라인의 린트 에러를 강제로 끄는 등의 임시방편을 써야 했는데요.

Next.js에서는 너무나 당연하게 동작하던 코드들이 여기서는 추가적인 튜닝을 요구하는 상황이 반복되기도 했습니다.

하지만 그는 이러한 불편함이 프레임워크의 본질적인 결함이라기보다는 성숙해가는 과정에서 겪는 성장통이라고 판단했거든요.

결국 서비스의 핵심 가치가 인터랙티브한 사용자 경험에 있다면 이러한 비용을 치르더라도 갈아탈 가치가 충분하다는 결론을 내렸습니다.

탠스택 스타트만의 독특한 구조적 특징

TanStack Start를 제대로 활용하기 위해서는 ‘start.ts’와 같은 설정 파일의 역할을 정확히 이해하는 것이 중요한데요.

Next.js의 미들웨어와 비슷한 역할을 하는 이 파일은 글로벌 수준의 로직을 처리하는 핵심적인 지점이 됩니다.

Cosden Codes는 이 파일의 설정 방식이 처음에는 다소 혼란스러웠지만 한 번 이해하고 나면 매우 강력한 통제권을 준다는 사실을 발견했습니다.

또한 데이터베이스 연결 시 클라이언트로 정보가 유출되는 것을 막기 위해 ‘create server only function’을 적절히 섞어 써야 한다는 점도 강조했거든요.

이런 세밀한 부분들은 아직 문서에 충분히 설명되어 있지 않아 직접 코드를 뜯어보며 익혀야 하는 영역이기도 합니다.

결론 자신에게 맞는 도구를 선택하는 지혜

Cosden Codes의 이번 이주기는 우리에게 기술 선택에 대한 중요한 메시지를 던져주고 있는데요.

아무리 대중적이고 강력한 Next.js라 할지라도 모든 프로젝트에 정답이 될 수는 없다는 사실입니다.

자신의 팀이 ‘React Query’에 익숙하고 클라이언트 사이드의 정교한 상태 관리가 핵심이라면 TanStack Start는 훌륭한 대안이 될 수 있습니다.

반대로 안정적인 에코시스템과 서버 레벨의 강력한 캐싱이 우선이라면 Next.js를 고수하는 것이 훨씬 현명한 선택일 것입니다.

중요한 것은 유행을 쫓는 것이 아니라 서비스의 본질과 팀의 역량에 가장 잘 맞는 도구를 선별해내는 혜안을 갖추는 일입니다.

프레임워크는 결국 문제를 해결하기 위한 수단일 뿐이며 그 자체가 목적이 되어서는 안 된다는 점을 잊지 마세요.

Cosden Codes는 비록 많은 우여곡절을 겪었지만 자신의 서비스에 최적화된 아키텍처를 찾았다는 점에서 이번 이주를 성공적이라고 자평했습니다.

여러분도 현재의 기술 스택에 의문을 던지고 새로운 가능성을 탐색하는 과정에서 진정한 성장의 기회를 발견하시길 바랍니다.

불완전한 도구라도 그것을 어떻게 요리하느냐에 따라 세상에 없던 멋진 서비스를 만들어낼 수 있음을 명심해야 합니다.

실전 튜토리얼 마이그레이션을 위한 핵심 체크리스트

만약 여러분도 Cosden Codes처럼 Next.js에서 TanStack Start로의 이주를 고민하고 있다면 몇 가지 필수적인 단계들을 점검해봐야 하는데요.

가장 먼저 수행해야 할 작업은 기존의 데이터 페칭 로직을 ‘TanStack Query’ 기반으로 재설계하는 일입니다.

Next.js의 서버 컴포넌트 내부에서 직접 수행하던 데이터 접근 로직을 별도의 함수로 분리하고 이를 서버 함수로 감싸는 작업이 필요하거든요.

이 과정에서 로직의 재사용성은 높아지지만 클라이언트와 서버 사이의 데이터 직렬화 제약을 항상 염두에 두어야 합니다.

그다음으로는 라우팅 구조를 ‘TanStack Router’의 파일 기반 라우팅 규칙에 맞춰 재배치하는 과정이 이어지는데요.

Next.js와 비슷해 보이지만 폴더 구조나 파일 명명 규칙에서 미세한 차이가 있어 꼼꼼한 확인이 필요합니다.

특히 각 라우트 파일에서 로더 함수를 정의하고 이를 통해 데이터를 주입하는 패턴에 익숙해지는 시간을 가져야 합니다.

마지막으로 기존에 사용하던 미들웨어나 서버 캐시 전략을 TanStack Start의 글로벌 미들웨어와 HTTP 캐시 제어 방식으로 전환하는 작업을 거치면 마이그레이션의 큰 산을 넘게 됩니다.

성공적인 전환을 위한 마인드셋

성공적인 이주를 위해서는 기술적인 준비만큼이나 유연한 사고방식을 갖추는 것이 무엇보다 중요한데요.

기존 프레임워크에서 당연하게 여겼던 관습들을 과감히 버리고 새로운 프레임워크가 제시하는 철학을 온전히 받아들여야 합니다.

버그나 문서 부족으로 인한 시행착오는 커뮤니티에 기여하고 자신만의 노하우를 쌓을 수 있는 기회로 생각하는 긍정적인 자세가 필요하거든요.

Cosden Codes 역시 수많은 ‘Discord’ 질문과 코드 삽질을 통해 자신만의 최적화된 워크플로우를 구축해 나갔음을 잊지 마세요.

이러한 도전적인 과정이야말로 평범한 개발자를 탁월한 엔지니어로 거듭나게 만드는 가장 빠른 지름길입니다.

프레임워크 이주는 단순한 코드 옮기기가 아니라 서비스의 기초를 다시 다지는 중대한 작업임을 기억하시길 바랍니다.

오늘 살펴본 Cosden Codes의 사례가 여러분의 기술적 선택과 도전 앞에 든든한 가이드라인이 되었기를 진심으로 바랍니다.

새로운 기술의 파도 위에서 두려움 없이 항해하며 여러분만의 멋진 결과물을 만들어내시길 응원하겠습니다.