유독 무거운 라우트 청크에 들어 있던 것은 그 화면을 그리는 코드와 관계없는 서버 모듈이었다. 라우트별로 코드를 나눴는데도 하나만 커져 원인을 설명하기 막막한 개발자라면, 이 감사 기록에서 비교할 근거를 찾을 수 있다. 기록은 청크의 내용물을 추적하고, 되돌림 실험과 반증 실험을 함께 사용해 원인을 검증 헬퍼 호출 한 줄까지 좁혔다.

이 글의 근거는 이 블로그와 다른 프로젝트에서 수행된 무인 자동 성능 감사다. 감사는 실험 결과와 한계를 문서 두 건으로 남겼으며, 최종 변경에 제품 코드 수정은 포함하지 않았다. 아래 수치는 그 감사 기록의 측정값이고, 실제 사용자 속도가 개선됐다는 결과는 아니다.

호출을 제거하자 청크가 줄었고, 다른 후보를 바꿔도 크기와 해시는 그대로였다. 이 대비가 호출 한 줄을 원인으로 확정한 근거다.

라우트 하나만 유독 무거운 이유부터 확인한다

청크는 빌드 도구가 나눈 자바스크립트 번들 조각이다. 감사 기록은 문제 라우트와 다음으로 큰 라우트의 청크를 raw 크기와 gzip 크기로 비교했다. 문제 청크는 다음으로 큰 청크의 4.7배(raw), 4.9배(gzip)였다.

감사 기록의 비교 대상rawgzip
문제 라우트 청크83.41 kB23.36 kB
다음으로 큰 라우트 청크17.61 kB4.79 kB
문제 청크의 상대 크기4.7배4.9배

기록에 남은 발견은 검증 라이브러리 런타임 전체와 서버 데이터베이스 스키마가 클라이언트 청크에 포함됐다는 것이다. 런타임 식별자가 청크에서 331회 등장했다는 측정도 함께 남아 있다. 크기 차이는 조사 대상을 가리켰고, 서버 전용 코드의 존재는 import 경로를 추적할 이유가 됐다.

같은 방식으로 조사한다면 비교할 빌드의 소스와 설정부터 맞춰야 한다. 같은 조건으로 다시 빌드해도 크기나 해시가 달라진다면, 그 변동 원인을 먼저 확인하는 편이 좋다. 이는 비교를 위한 권장 절차이며, 이 감사에서 빌드의 결정성을 별도로 검증했다는 뜻은 아니다.

값 import 한 줄이 체인 전체를 끌고 온다

감사가 추적한 출발점은 클라이언트에서 렌더되는 라우트 컴포넌트의 검증 헬퍼 호출이었다. 그 헬퍼는 서버 액션 모듈을 값으로 참조했고, 액션 모듈은 서버 데이터베이스 모듈을 거쳐 스키마 정의로 이어졌다. 스키마 정의가 검증 라이브러리 런타임을 끌고 오면서 호출 한 줄이 서버 쪽 의존성까지 연결했다.

클라이언트에서 렌더되는 라우트 컴포넌트가 검증 헬퍼를 호출하고, 그 헬퍼가 서버 액션 모듈을 값으로 import한다. 서버 액션 모듈은 서버 데이터베이스 모듈로, 다시 스키마 정의로 이어지며, 스키마 정의가 검증 라이브러리 런타임을 끌고 와 클라이언트 번들에 서버 쪽 의존성이 연결된다.
값 import 한 줄은 트리 셰이킹으로 지워지지 않고 서버 모듈 체인 전체를 클라이언트 번들로 연결한다.

값 import는 실행에 쓰이는 함수나 객체를 가져온다. 트리 셰이킹은 사용하지 않는 코드를 제거하는 최적화지만, 실제 호출에 필요한 값까지 없앨 수는 없다. 타입 검사에만 쓰이는 타입 전용 import와 달리, 이 사례의 참조는 실행 코드로 이어져 있었다.

해당 프로젝트에는 클라이언트 라우트가 검증 라이브러리·데이터베이스·서버 액션 모듈을 값으로 import하지 않는다는 계약이 이미 있었다. 그 계약이 문서로 정해져 있었어도 이번 유입을 막지는 못했다. 문서의 규칙과 빌드 시점에 강제되는 규칙 사이에 빈틈이 있었다는 것이 이 기록에서 읽을 수 있는 문제다.

되돌림 실험으로 상한 효과부터 잰다

감사 기록의 되돌림 실험은 라우트 컴포넌트 안의 검증 헬퍼 호출 한 줄만 제거하고 재빌드하는 방식이었다. 그 결과 문제 청크는 10.77 kB raw / 3.34 kB gzip으로 줄었다. 기록에 적힌 감소율은 −87% raw, −86% gzip이다.

문제 라우트 청크rawgzip
호출 제거 전83.41 kB23.36 kB
호출 제거 후 재빌드10.77 kB3.34 kB
기록된 감소율−87%−86%

감사는 이 값을 제안 수정의 상한 효과로 남겼다. 호출을 없앤 실험이므로, 필요한 검증 기능을 보존하는 최종 수정도 정확히 같은 크기가 된다는 보장은 아니다. 또한 이 결과만으로 액션 전용 경로라는 다른 후보까지 배제한 것은 아니었다.

반증 실험으로 다른 후보를 지운다

별도의 반증 실험에서는 액션 전용 함수를 동적 import로 바꾸고 빌드했다. 이 빌드의 청크 크기와 해시는 변경 전과 완전히 동일했다. 감사는 이 결과를 근거로 액션 전용 경로는 이미 트리 셰이킹이 정상적으로 작동하고 있다고 판단했다.

왼쪽 열은 되돌림 실험이다. 라우트 컴포넌트 안의 검증 헬퍼 호출 한 줄을 제거하고 재빌드하자 문제 청크가 10.77 kB raw, 3.34 kB gzip으로 줄었고 감소율은 raw 87%, gzip 86%였다. 오른쪽 열은 반증 실험이다. 액션 전용 함수를 동적 import로 바꿔 빌드했더니 청크 크기와 해시가 변경 전과 완전히 같았고, 이 경로는 트리 셰이킹이 정상이라 후보에서 배제됐다.
두 실험을 나란히 놓으면 크기를 줄인 것은 클라이언트 렌더 경로의 호출 한 줄이고 액션 전용 경로는 원인이 아니라는 결론이 선다.

호출 제거 실험에서는 크기가 줄었지만, 액션 전용 함수의 import 방식을 바꾼 실험에서는 산출물이 그대로였다. 감사는 이 두 결과를 합쳐 클라이언트 렌더 경로의 검증 헬퍼 호출 한 줄을 원인으로 확정했다. 여기서 동적 import는 후보를 가르는 실험 수단이었으며, 서버 코드의 클라이언트 유입을 막는 수정으로 적용된 것은 아니다.

baseline 없이는 회귀라 부를 수 없다

감사에는 저장소에 체크인된 성능 baseline, 즉 비교할 과거 측정치가 없었다. baseline을 캡처하는 스크립트는 있었지만 기본 출력 디렉터리는 존재하지 않았다. 따라서 현재 청크의 크기와 원인은 확인했어도, 이전보다 나빠진 회귀인지는 확정하지 못했다.

Lighthouse·LCP·INP, 프로덕션 데이터베이스 지연, 콜드 스타트 CPU도 측정하지 않았다. 청크 크기 감소만으로 페이지 로딩이나 입력 반응이 얼마나 빨라지는지 답할 수는 없다. 사용자 체감 개선과 서버 쪽 영향은 별도 측정이 필요한 항목으로 남는다.

질문감사 기록이 답한 범위
어느 청크가 왜 무거운가크기 비교와 의존성 추적으로 확인
어느 호출이 원인인가되돌림·반증 실험을 함께 사용해 확정
최종 수정이 적용됐는가감사 결과는 문서로 남았으며 제품 코드 변경 없음
언제부터 나빠졌는가baseline이 없어 회귀 여부 미확정
사용자 속도와 서버 성능이 개선됐는가Lighthouse·LCP·INP, DB 지연, 콜드 스타트 CPU 미측정

이 기록을 수정 기준으로 삼는다면 클라이언트 진입점의 값 참조부터 검토할 수 있다. 타입만 필요하면 타입 전용 import를 사용하고, 서버 전용 값이 필요하면 해당 호출을 서버 쪽으로 옮기는 방향을 검토한다. 서버 전용 모듈임을 파일 이름에 드러내는 것도 경계를 읽기 쉽게 하는 권장 방법이다.

계약을 강제할 후보로는 import를 제한하는 린트 규칙, 서버 전용 모듈의 런타임 마커, 클라이언트 청크의 금지 모듈 검사가 있다. 이 셋은 이번 감사에서는 아직 실제로 붙이지 않았다. 다음 작업으로 남겨 둔 항목이며, 감사 기록이 최우선 후속 과제로 명시한 것은 baseline 산출물 확보였다.

빌드 구조를 비교해 보고 싶다면 번들러 없이 정적 사이트로 앱을 만든 경험을 함께 읽을 수 있다. 다른 원인 추적 기록은 프로그래밍 카테고리에서 찾을 수 있다. 자신의 라우트를 조사할 때도 청크의 내용, 후보별 실험 결과, 아직 측정하지 않은 항목을 따로 남기면 수정의 근거와 한계를 구분할 수 있다.