Next.js

Sophonz Next.js SDK는 App Router 앱의 브라우저·서버 모니터링을 하나의 설정으로 구성합니다 — 클라이언트의 SophonzProvider와 서버의 register()가 하나의 trace를 공유합니다.

언제 일반 SDK 대신 이걸 쓰나요

• App Router 앱에서 브라우저와 서버 텔레메트리를 하나의 trace로 묶고, 설정도 두 벌이 아닌 한 벌로 관리하고 싶을 때.
• @sophonz/browser-sdk와 @sophonz/node-sdk를 각각 붙이고 앱 이름·키를 수동으로 맞춰야 했을 프로젝트.
• 한쪽만 필요하거나, Pages Router를 쓰거나, Next가 아닌 Node 서버라면 Web SDK나 Node.js SDK를 직접 사용하세요.

제공 기능

• SophonzProvider — app/layout.tsx에 한 번 마운트하는 Client Component. 마운트 시 @sophonz/browser-sdk를 초기화하며, 동적으로 import하므로 하이드레이션 이후에만 비용이 발생합니다.
• register() — instrumentation.ts로 연결하는 서버 진입점. 어떤 요청도 처리되기 전에 @sophonz/node-sdk를 시작해 자동 계측이 제때 모듈을 패치할 수 있게 합니다. Edge 런타임에서는 아무 동작도 하지 않습니다.
• 공유 설정 해석 — 양쪽 모두 같은 resolveConfig()를 호출하므로, appName, appVersion, appKey, project, deploymentEnvironment가 하나의 NEXT_PUBLIC_SOPHONZ_* 환경 변수 집합(또는 코드로 설정 시 같은 설정 객체)에서 나옵니다.
• 하나로 이어지는 trace — 브라우저가 기본적으로 동일 origin 요청에 traceparent를 붙이므로, 페이지 로드와 그 페이지가 호출하는 API 라우트가 하나의 trace로 보입니다.

동작 방식

1. 클라이언트 — SophonzProvider가 환경 변수를 기준으로 SophonzNextConfig를 해석하고, 마운트 시 @sophonz/browser-sdk를 동적으로 import합니다.
2. 서버 — 서버 프로세스당 한 번 instrumentation.ts에서 호출되는 register()가 같은 설정을 해석하고, 서버 SDK의 OTLP 엔드포인트를 collectorUrl로 지정한 뒤 @sophonz/node-sdk의 initSDK()를 호출합니다.
3. 양쪽 모두 그 위에 Sophonz 권장 기본값을 적용합니다. 서버는 betaMode를 켜고(setTraceAttributes()에 필요) 시작 배너를 끕니다. 브라우저는 Intercom 존재 여부 폴링을 끕니다.