Next.js Script 전략 (로드순서, CSS경로, 플러그인디버깅)
솔직히 말하면, 저는 PHP에서 Next.js로 넘어가면서 스크립트 로딩 방식이 이렇게 다를 거라고는 생각조차 못했습니다. Annotator.js의 Touch 플러그인이 작동하지 않았던 이유를 찾는 데 꽤 오랜 시간을 썼는데, 결론은 JavaScript가 아니라 CSS 문제였습니다. 그 과정에서 next/script의 로딩 전략과 빌드 환경의 차이를 제대로 이해하게 됐습니다.
next/script의 로딩 전략, 생각보다 선택지가 많습니다
기존 PHP 프로젝트에서는 document.createElement(“script”)로 스크립트 요소를 직접 만들고, onload 이벤트로 다음 파일을 순차적으로 불러오는 방식을 썼습니다. 의존성이 있는 라이브러리끼리 로드 순서를 직접 제어할 수 있었기 때문에 나름 익숙하고 편했습니다. 그런데 플러그인이 하나씩 늘어날수록 코드가 콜백 지옥 수준으로 복잡해지는 문제가 있었습니다.
Next.js에서는 next/script 컴포넌트를 사용해 이 문제를 구조적으로 해결할 수 있습니다. 이 컴포넌트는 strategy라는 속성으로 스크립트의 로딩 시점을 지정합니다. 제가 직접 써보면서 정리한 네 가지 전략은 다음과 같습니다.
- beforeInteractive: 페이지 하이드레이션(hydration, 서버에서 내려온 HTML에 React가 이벤트를 연결하는 과정)이 시작되기 전에 로드됩니다. 쿠키 동의 배너나 봇 감지 스크립트처럼 페이지가 인터랙티브해지기 전에 반드시 필요한 스크립트에 씁니다.
- afterInteractive: 기본값입니다. 초기 하이드레이션이 끝난 뒤 로드되며, 구글 태그 매니저나 애널리틱스처럼 빠르게 불러오되 첫 렌더링을 막으면 안 되는 스크립트에 적합합니다.
- lazyOnload: 브라우저 유휴 시간(idle time, 브라우저가 당장 처리할 작업이 없는 여유 시간)을 활용해 로드합니다. 채팅 위젯이나 소셜 미디어 버튼처럼 초기 로드에 급하지 않은 것들에 씁니다.
- worker: 웹 워커(Web Worker, 메인 스레드와 별도로 백그라운드에서 실행되는 스크립트 환경)로 오프로드하는 실험적 전략입니다. 아직 app 디렉토리에서는 정식 지원이 안 되기 때문에 저는 아직 실제로 적용해 본 적이 없습니다.
처음에 저는 의존성 순서가 중요한 라이브러리들을 전부 beforeInteractive로 설정했습니다. “일단 먼저 불러오면 안전하지 않을까”라는 생각이었는데, 이게 오히려 문제의 출발점이 됐습니다. 모든 스크립트에 beforeInteractive를 쓰는 것이 정답이라고 생각하시는 분들도 있을 것 같은데, 실제로 써보니 전략마다 목적이 다르고 잘못 쓰면 로그조차 안 찍히는 경우가 생깁니다.
CSS를 import했더니 빌드가 깨진 이유
JavaScript 로딩 방식을 정리하면서, CSS도 Next.js 방식으로 바꾸기로 했습니다. 기존에는 정적 파일로 HTML에 연결하던 것들을 import 구문으로 변경했습니다. 그런데 빌드를 돌리자마자 오류가 터졌습니다.
오류 메시지는 “Module not found: Can’t resolve ‘../images/handle.png'”였습니다. CSS 파일 안에 존재하지 않는 이미지 경로가 참조되어 있었던 겁니다. PHP 환경에서는 이 문제가 전혀 드러나지 않았는데, 이유가 있었습니다.
PHP에서 CSS를 정적 리소스로 연결하면 브라우저가 해당 파일을 받아서 파싱합니다. 이 과정에서 url() 안의 경로가 존재하지 않아도, 해당 이미지 요청이 404로 실패할 뿐 빌드 자체는 멈추지 않습니다. 반면 Next.js에서 CSS를 import하면 번들러(bundler, 여러 파일을 하나로 묶어주는 도구로 Next.js는 내부적으로 webpack 또는 Turbopack을 사용합니다)가 CSS 파일을 분석하면서 상대 경로로 참조된 파일들까지 함께 처리하려 합니다. 이때 파일이 없으면 빌드 단계에서 오류가 납니다.
일반적으로 “CSS 파일만 확인하면 된다”고 생각하기 쉬운데, 제 경험상 CSS 내부에서 참조하는 이미지나 폰트 파일까지 함께 점검해야 이런 문제를 미리 잡을 수 있습니다. 해결 방법은 상황에 따라 다릅니다. 해당 이미지가 실제로 필요하다면 올바른 경로에 파일을 배치하고 CSS의 url() 경로를 맞게 수정하면 됩니다. 반대로 이미지가 불필요한 경우라면 해당 CSS 규칙 자체를 제거하는 것이 깔끔합니다. Next.js 공식 문서의 정적 자산 처리 가이드를 참고하면 퍼블릭 폴더 구조와 경로 설정 방식을 더 명확하게 파악할 수 있습니다.
플러그인은 등록됐는데 화면에 안 보인다면
빌드 오류를 잡고 나서, Touch 플러그인이 실제로 제대로 작동하는지 확인에 들어갔습니다. 브라우저에서 직접 파일 경로에 접근해보니 JavaScript 코드가 정상적으로 표시됐고, 경로 자체는 문제가 없었습니다.
다음으로 onLoad 이벤트를 활용해 로드 여부를 추적했습니다. 처음에 beforeInteractive 전략을 쓸 때는 onLoad 로그가 아예 찍히지 않았고, afterInteractive로 바꾸자 로그가 정상 출력됐습니다. 여기서 또 하나 배운 점인데, onLoad는 afterInteractive와 lazyOnload에서만 동작합니다. 공식 문서를 보면 beforeInteractive에서는 onReady를 사용해야 한다고 나와 있습니다(Next.js Script 컴포넌트 API 참조). 저는 이 부분을 몰라서 한참을 헤맸습니다.
그런데 스크립트가 로드됐다는 로그가 찍혀도 화면에는 아무것도 나타나지 않았습니다. 브라우저 콘솔에서 window.Annotator?.Plugin을 직접 찍어봤더니 Touch 플러그인이 등록된 것을 확인할 수 있었습니다. editor, viewer, utils 같은 내부 객체도 존재했습니다. 이 시점에서 문제가 JavaScript에 있지 않다는 걸 확신하게 됐습니다.
플러그인이 등록됐는데 화면에 보이지 않는다면 보통 두 가지를 의심해야 합니다. DOM 요소가 실제로 생성됐는지, 그리고 그 요소에 CSS가 제대로 적용됐는지입니다. 개발자 도구 Elements 패널에서 플러그인 관련 DOM 요소는 존재했지만, 시각적으로 기대했던 모습이 아니었습니다. 정확히는 스타일이 빠진 상태였습니다.
결국 문제는 CSS였고, 디버깅 순서가 핵심이었습니다
CSS 파일과 이미지 경로를 정리하고 스타일을 수정하자 Touch 플러그인의 UI가 정상적으로 표시됐습니다. JavaScript 코드는 처음부터 문제가 없었고, 라이브러리 로드 순서도 실제 원인이 아니었습니다. 저는 처음에 이게 next/script의 로딩 전략 문제라고 단정하고 시간을 꽤 썼는데, 솔직히 이건 예상 밖의 경험이었습니다.
이번 경험에서 제가 가장 크게 체감한 것은 디버깅 순서의 중요성입니다. 브라우저 콘솔에 오류가 없다고 해서 기능이 정상인 건 아닙니다. 반대로 화면에 뭔가 안 보인다고 해서 무조건 JavaScript를 의심하면 시간을 낭비하게 됩니다. 제가 정리한 확인 순서는 다음과 같습니다.
- 해당 JavaScript 파일이 네트워크 탭에서 정상적으로 요청되는가?
- 스크립트 실행 후 onLoad 또는 onReady 콜백이 호출되는가?
- window 객체에 플러그인이 등록되어 있는가?
- 플러그인이 대상 DOM 요소에 실제로 적용되었는가?
- 플러그인이 생성하는 DOM 요소가 Elements 패널에 존재하는가?
- 해당 요소에 필요한 CSS 스타일이 정상적으로 적용되어 있는가?
이 순서대로 하나씩 확인하면 문제가 어느 단계에서 발생했는지 상당히 빠르게 좁혀집니다. 처음부터 이 방식으로 접근했더라면 훨씬 일찍 해결했을 텐데, 그렇지 않았기 때문에 이번 경험이 더 오래 기억에 남을 것 같습니다.
자주 묻는 질문
Q. next/script의 beforeInteractive와 afterInteractive는 어떻게 구분해서 써야 하나요?
A. beforeInteractive는 페이지가 인터랙티브해지기 전에 반드시 실행되어야 하는 스크립트에만 씁니다. 쿠키 동의 관리자나 봇 탐지기 정도가 대표적입니다. 대부분의 서드파티 스크립트는 afterInteractive가 더 적합합니다. 모든 것에 beforeInteractive를 쓰면 onLoad 이벤트가 작동하지 않는 등 예상치 못한 문제가 생길 수 있어서, 저는 beforeInteractive는 꼭 필요한 경우에만 제한적으로 사용하고 있습니다.
Q. PHP에서 Next.js로 라이브러리를 옮길 때 CSS import 방식으로 바꿔야 하나요?
A. 반드시 그런 건 아닙니다. CSS를 public 폴더에 두고 HTML link 태그로 연결하거나 _document에서 불러오는 방식을 유지할 수도 있습니다. 다만 import 방식을 쓰면 번들러가 경로를 분석하기 때문에 CSS 내부에 존재하지 않는 파일을 참조하는 경우 빌드 단계에서 오류가 납니다. 어떤 방식이 맞는지는 라이브러리의 구조와 참조하는 정적 리소스 상황을 먼저 파악한 뒤 결정하는 것이 좋습니다.
Q. 플러그인이 window 객체에 등록됐는데 화면에 보이지 않을 때 가장 먼저 확인할 것은?
A. 브라우저 개발자 도구의 Elements 패널에서 플러그인이 생성하는 DOM 요소가 실제로 있는지 먼저 확인합니다. 요소가 있다면 Styles 패널에서 CSS가 제대로 적용됐는지 살펴보면 됩니다. JavaScript와 CSS 문제를 구분하는 것이 핵심인데, 제 경험상 이 두 가지를 혼동하면 디버깅 시간이 두 배로 늘어납니다.
Q. next/script의 worker 전략은 언제 쓸 수 있나요?
A. worker 전략은 현재 실험적 기능으로, pages 디렉토리에서만 사용할 수 있고 app 디렉토리에서는 아직 지원되지 않습니다. next.config.js에서 nextScriptWorkers 플래그를 활성화해야 하며, 모든 서드파티 스크립트가 웹 워커 환경에서 정상적으로 동작한다는 보장도 없습니다. 안정성이 확보되지 않은 만큼 프로덕션 환경에서는 신중하게 사용하는 것이 맞다고 봅니다.
PHP 프로젝트를 Next.js로 옮기는 작업은 단순한 코드 이식이 아니라는 걸 이번 경험으로 다시 확인했습니다. 빌드 환경이 다르고, 정적 리소스를 처리하는 방식도 다릅니다. 외부 라이브러리를 마이그레이션할 때는 JavaScript 파일만 옮기는 것으로 끝나지 않고 CSS와 이미지 경로까지 함께 점검해야 합니다. 비슷한 상황에 처한 분들께는 디버깅 순서를 미리 정해두고 단계별로 확인하는 방식을 추천합니다.
—
참고: https://nextjs-ko.org/docs/app/api-reference/components/script
https://nextjs.org/docs/app/building-your-application/optimizing/static-assets