🗺️ Next.js Route Visualizer

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

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

✨ 특징

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

🚀 빠른 시작

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

1# 현재 디렉터리 분석 (기본: 그래프 다이어그램)
2npx @choi2021/next-route-visualizer
3
4# 인터랙티브 HTML 리포트 생성
5npx @choi2021/next-route-visualizer report
6
7# 특정 프로젝트 분석
8npx @choi2021/next-route-visualizer ./my-next-app
9npx @choi2021/next-route-visualizer report ./my-next-app

명령어 옵션

1# 기본 그래프 시각화
2npx @choi2021/next-route-visualizer map [project-path]
3
4# 인터랙티브 HTML 리포트
5npx @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/ 구조)

💡 사용 예시

1$ npx @choi2021/next-route-visualizer report
2
3📊 Next.js Route HTML Report Generator v1.0.0
4
5🔄 라우트 분석 중...
6📊 HTML 리포트 생성 중...
7
8✅ HTML 리포트가 생성되었습니다: route-report.html
9📊 총 9개 페이지, 139개 연결 분석 완료
10
11🌐 브라우저에서 리포트를 열었습니다!

🎨 시각화 모드

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

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

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

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

📊 출력 데이터 구조

route-graph.json의 구조:

1{
2  "nodes": [
3    {
4      "id": "/",
5      "path": "/",
6      "type": "page",
7      "filePath": "pages/index.tsx",
8      "fileSize": 2203,
9      "metadata": { "depth": 0, "segments": [""] }
10    }
11  ],
12  "edges": [
13    {
14      "source": "/",
15      "target": "/about",
16      "method": "link",
17      "lineNumber": 25,
18      "codeSnippet": "<Link href='/about'>",
19      "fileName": "pages/index.tsx"
20    }
21  ],
22  "summary": {
23    "totalPages": 9,
24    "totalConnections": 139,
25    "avgConnections": 15.4
26  }
27}

🔍 연결 분석 타입

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

🛠️ 개발 및 디버깅

로컬 개발

1git clone https://github.com/your-username/next-route-map.git
2cd next-route-map
3npm install
4npm run build
5
6# 예제 프로젝트 테스트
7npm run test:example
8
9# HTML 리포트 테스트
10npm run test:report

🤝 기여하기

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

📄 라이선스

MIT License

---

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

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

동적 함수 분석

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

1// 1. 조건부 동적 함수 (✅ 모든 가능한 경로 감지)
2const getRoute = () => {
3  if (condition) {
4    return V2_Routes.ADMIN_PANEL(); // → /v2/admin/panel
5  } else {
6    return Routes.PROFILE(); // → /profile
7  }
8};
9
10const handleClick = () => {
11  Router.push(getRoute()); // 두 경로 모두 시각화됨!
12};
13
14// 2. 화살표 함수 Routes 상수 (✅ 지원)
15export const V2_Routes = {
16  ADMIN_PANEL: () => "/v2/admin/panel",
17  USER_PROFILE: (id) => `/v2/user/${id}`,
18};
19
20// 3. getServerSideProps 리디렉션 (✅ 지원)
21export async function getServerSideProps() {
22  if (!authenticated) {
23    return { redirect: { destination: "/login" } };
24  }
25}
26
27// 4. 대소문자 구분 (✅ 모두 감지)
28Router.push(Routes.HOME()); // 대문자 Router
29router.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 내 네비게이션
• ✅ 훅 기반 네비게이션