@choi2021/next-route-visualizer

🗺️ Next.js Route Visualizer

Next.js 프로젝트의 라우트 구조와 네비게이션을 한 눈에 시각화해보세요!

한 번의 명령어로 라우트 그래프 JSON과 인터랙티브 HTML 리포트를 생성합니다.

✨ 특징

• 🚀 원클릭 실행: npx 명령어 하나로 즉시 시각화
• 📊 라우트 분석: 페이지와 다이내믹 라우트 관계 추적
• 🎯 동적 함수 분석: Router.push(getRoute())와 같은 동적 함수 호출 내부 분석
• 🔍 고급 네비게이션 감지: Routes 상수, 화살표 함수, 조건부 네비게이션 지원
• 🎨 두 가지 시각화 모드:
  • 📈 그래프 다이어그램: 드래그, 줌, 필터링 가능한 노드-링크 시각화
  • 📋 인터랙티브 리포트: 페이지 선택형 연결 탐색 인터페이스
• 💾 JSON 출력: 다른 도구에서도 활용 가능한 데이터
• 🌐 자동 브라우저: 생성 즉시 브라우저에서 열림

🚀 빠른 시작

Next.js 프로젝트에서 바로 실행

# 현재 디렉터리 분석 (기본: 그래프 다이어그램)
npx @choi2021/next-route-visualizer

# 인터랙티브 HTML 리포트 생성
npx @choi2021/next-route-visualizer report

# 특정 프로젝트 분석
npx @choi2021/next-route-visualizer ./my-next-app
npx @choi2021/next-route-visualizer report ./my-next-app

명령어 옵션

# 기본 그래프 시각화
npx @choi2021/next-route-visualizer map [project-path]

# 인터랙티브 HTML 리포트
npx @choi2021/next-route-visualizer report [project-path] [-o output.html]

결과

그래프 시각화 (map 명령어):

• route-graph.json - 라우트 데이터
• route-visualizer.html - 노드-링크 그래프 시각화

HTML 리포트 (report 명령어):

• route-graph.json - 라우트 데이터
• route-report.html - 페이지 선택형 인터랙티브 리포트

📋 시스템 요구사항

• Node.js 14.0.0 이상
• Next.js 프로젝트 (pages/ 또는 src/pages/ 구조)

💡 사용 예시

$ npx @choi2021/next-route-visualizer report

📊 Next.js Route HTML Report Generator v1.0.0

🔄 라우트 분석 중...
📊 HTML 리포트 생성 중...

✅ HTML 리포트가 생성되었습니다: route-report.html
📊 총 9개 페이지, 139개 연결 분석 완료

🌐 브라우저에서 리포트를 열었습니다!

🎨 시각화 모드

1. 📈 그래프 다이어그램 (map)

• 컬러 코딩: 페이지(파란색), 다이내믹 라우트(주황색)
• 인터랙티브 그래프: 노드 드래그, 줌 인/아웃, 팬
• 세부 정보: 호버시 파일 경로, 코드 스니펫, 라인 번호 표시
• 연결 추적: 페이지간 네비게이션 관계 시각화

2. 📋 인터랙티브 리포트 (report)

• 사이드바: 연결 수 기준 정렬된 페이지 목록
• 페이지 상세: 선택된 페이지의 incoming/outgoing 연결 표시
• 프로젝트 통계: 전체 페이지, 연결 수, 평균 연결 수
• 검색 기능: 페이지 경로 실시간 검색
• 클릭 네비게이션: 연결된 페이지 간 쉬운 이동

📊 출력 데이터 구조

route-graph.json의 구조:

{
  "nodes": [
    {
      "id": "/",
      "path": "/",
      "type": "page",
      "filePath": "pages/index.tsx",
      "fileSize": 2203,
      "metadata": { "depth": 0, "segments": [""] }
    }
  ],
  "edges": [
    {
      "source": "/",
      "target": "/about",
      "method": "link",
      "lineNumber": 25,
      "codeSnippet": "<Link href='/about'>",
      "fileName": "pages/index.tsx"
    }
  ],
  "summary": {
    "totalPages": 9,
    "totalConnections": 139,
    "avgConnections": 15.4
  }
}

🔍 연결 분석 타입

• link: Next.js Link 컴포넌트
• router: router.push(), router.replace() 등
• component: 컴포넌트를 통한 간접 네비게이션

🛠️ 개발 및 디버깅

로컬 개발

git clone https://github.com/your-username/next-route-map.git
cd next-route-map
npm install
npm run build

# 예제 프로젝트 테스트
npm run test:example

# HTML 리포트 테스트
npm run test:report

🤝 기여하기

버그 리포트와 기능 제안은 GitHub Issues에서 환영합니다.

📄 라이선스

MIT License

⭐ 프로젝트가 유용하다면 GitHub에서 별표를 눌러주세요!

🎯 고급 분석 기능 (v1.1.0)

동적 함수 분석

이제 다음과 같은 복잡한 네비게이션 패턴도 정확히 분석합니다:

// 1. 조건부 동적 함수 (✅ 모든 가능한 경로 감지)
const getRoute = () => {
  if (condition) {
    return V2_Routes.ADMIN_PANEL(); // → /v2/admin/panel
  } else {
    return Routes.PROFILE(); // → /profile
  }
};

const handleClick = () => {
  Router.push(getRoute()); // 두 경로 모두 시각화됨!
};

// 2. 화살표 함수 Routes 상수 (✅ 지원)
export const V2_Routes = {
  ADMIN_PANEL: () => "/v2/admin/panel",
  USER_PROFILE: (id) => `/v2/user/${id}`,
};

// 3. getServerSideProps 리디렉션 (✅ 지원)
export async function getServerSideProps() {
  if (!authenticated) {
    return { redirect: { destination: "/login" } };
  }
}

// 4. 대소문자 구분 (✅ 모두 감지)
Router.push(Routes.HOME()); // 대문자 Router
router.push(Routes.PROFILE()); // 소문자 router

지원하는 네비게이션 패턴

• ✅ 정적 경로: "/dashboard", '/profile'
• ✅ Routes 상수: Routes.HOME, ROUTES.DASHBOARD
• ✅ 함수형 Routes: Routes.PROFILE(), V2_Routes.ADMIN()
• ✅ 동적 함수 호출: Router.push(getRoute())
• ✅ 조건부 리턴: if/else 블록 내 네비게이션
• ✅ 템플릿 리터럴: `/dashboard?tab=${tab}`
• ✅ getServerSideProps 리디렉션
• ✅ useEffect 내 네비게이션
• ✅ 훅 기반 네비게이션