Next.js Render Analyzer

Next.js 프로젝트의 렌더링 전략(SSG/SSR/ISR/CSR)과 컴포넌트 타입(서버/클라이언트)을 분석하는 CLI 도구입니다.

왜 만들었나요?

Next.js App Router를 사용하면서 이런 고민을 해본 적 있으신가요?

• "이 컴포넌트가 서버에서 돌아가는 거야, 클라이언트에서 돌아가는 거야?"
• "use client를 어디에 붙여야 하지?"
• "우리 프로젝트에 클라이언트 컴포넌트가 너무 많은 건 아닐까?"
• "이 페이지는 SSG야 SSR이야? ISR은 제대로 설정된 거 맞아?"

Next.js 13+ App Router는 강력하지만, 프로젝트가 커지면 각 컴포넌트가 어디서 실행되는지 파악하기 어려워집니다.

해결하고자 하는 문제

1. 컴포넌트 타입 파악의 어려움

   • 파일을 하나하나 열어서 'use client'가 있는지 확인해야 함
   • 부모가 클라이언트 컴포넌트면 자식도 자동으로 클라이언트가 되는데, 이걸 추적하기 어려움

2. 렌더링 전략 혼란

   • revalidate 등 설정이 분산되어 있음
   • 실제로 어떤 전략으로 렌더링되는지 한눈에 보기 어려움

이 도구가 제공하는 것

• 프로젝트 전체 스캔: 모든 페이지와 컴포넌트를 자동으로 찾아서 분석
• 컴포넌트 타입 분류: 서버/클라이언트 컴포넌트 자동 분류
• 렌더링 전략 감지: SSG, SSR, ISR, CSR 자동 감지
• 분류 이유 설명: 왜 그렇게 분류되었는지 이유 제공
• 컴포넌트 트리 시각화: 의존성 관계를 트리로 표시

설치

npm install next-render-analyzer

로컬 개발용 설치

git clone https://github.com/khwww/render-analyzer.git
cd render-analyzer
npm install
npm run build
npm link

사용법

# 기본 분석
next-render-analyzer ./my-next-app

# 상세 정보 출력
next-render-analyzer ./my-next-app --detailed

# 컴포넌트 트리 출력
next-render-analyzer ./my-next-app --tree

# JSON 형식 출력
next-render-analyzer ./my-next-app --json

또는 빌드 없이 개발 모드로 실행:

npm run dev -- ./my-next-app

출력 예시

============================================================
  Next.js Render Analyzer
============================================================

[ 페이지별 렌더링 방식 ]
------------------------------------------------------------
app/page.tsx
  -> SSG (Static Site Generation)

app/blog/[slug]/page.tsx
  -> ISR (Incremental Static Regeneration)
  -> revalidate: 60초

[ 서버 컴포넌트 ]
------------------------------------------------------------
[S] Header
    파일: components/Header.tsx
    async 컴포넌트

[ 클라이언트 컴포넌트 ]
------------------------------------------------------------
[C] SearchBar
    파일: components/SearchBar.tsx
    Hooks: useState, useEffect

[ 통계 ]
------------------------------------------------------------
총 컴포넌트: 15개
  서버 컴포넌트: 10개
  클라이언트 컴포넌트: 5개

분석 항목

렌더링 전략

전략	설명	감지 방법
SSG	빌드 시 정적 생성	기본값, dynamic = 'force-static'
SSR	요청 시 서버 렌더링	cookies(), headers(), searchParams, fetch no-store, dynamic = 'force-dynamic'
ISR	주기적 재생성	revalidate export
CSR	클라이언트에서 렌더링	'use client' + Hooks

컴포넌트 타입

타입	설명	감지 방법
Server	서버에서만 실행	기본값 (use client 없음)
Client	브라우저에서 실행	'use client' 지시어

감지 기능

컴포넌트 분석

• 'use client' 지시어 감지
• React Hook 사용 감지 (useState, useEffect 등)
• async 컴포넌트 감지
• 이벤트 핸들러 감지 (onClick 등)

렌더링 전략 감지

• export const revalidate 감지 (ISR)
• export const dynamic 감지 (force-dynamic, force-static)
• cookies() 함수 사용 감지 (SSR)
• headers() 함수 사용 감지 (SSR)
• searchParams 파라미터 사용 감지 (SSR)
• fetch with cache: 'no-store' 감지 (SSR)

라이브러리로 사용하기

import { analyzeProject, analyzeFile, analyzePage } from "next-render-analyzer";

// 프로젝트 전체 분석
const result = analyzeProject("./my-next-app");
console.log(result.pages);      // PageAnalysis[]
console.log(result.components); // FileAnalysis[]

// 단일 파일 분석
const file = analyzeFile("./components/Button.tsx");
console.log(file.componentType); // "SERVER" | "CLIENT"

// 페이지 분석
const page = analyzePage("./app/page.tsx");
console.log(page.renderStrategy); // "SSG" | "SSR" | "ISR" | "CSR"

기술 스택

• AST 파싱: Babel Parser로 코드를 파싱하여 정확한 분석
• TypeScript: 타입 안정성 보장
• Jest: 유닛 테스트
• Dual Package: CommonJS와 ESM 모두 지원

개발

# 의존성 설치
npm install

# 개발 모드 실행
npm run dev

# 빌드
npm run build

# 테스트
npm test

# 린트
npm run lint

라이선스

MIT