🗺️ Next.js Route Map

Next.js 프로젝트의 라우트 구조를 인터랙티브한 시각적 다이어그램으로 변환하는 CLI 도구

✨ 특징

• 🚀 간단한 사용법: 한 줄 명령어로 라우트 맵 생성
• 🎨 인터랙티브 시각화: Cytoscape.js 기반의 동적 그래프
• 📱 모든 라우트 타입 지원: 페이지, API, 동적 라우트 모두 감지
• 🔗 네비게이션 추적: router.push(), Link 컴포넌트 연결 관계 분석
• 📄 단일 HTML 파일: 서버 없이 브라우저에서 바로 실행
• 🎯 제로 설정: 별도 설정 없이 즉시 사용 가능

🚀 빠른 시작

npx로 즉시 사용 (권장)

npx next-route-map map --path ./your-nextjs-project

글로벌 설치

npm install -g next-route-map
next-route-map map --path ./your-nextjs-project

📖 사용법

기본 사용법

# 현재 디렉토리의 Next.js 프로젝트 분석
npx next-route-map map

# 특정 경로의 프로젝트 분석
npx next-route-map map --path ./my-next-app

# 도움말 보기
npx next-route-map --help

명령어 옵션

next-route-map map [options]

Options:
  -p, --path <path>     Next.js 프로젝트 경로 (기본값: ".")
  -h, --help           도움말 표시

🎨 생성되는 시각화

도구를 실행하면 route-visualizer.html 파일이 생성되며, 다음과 같은 기능을 제공합니다:

📊 노드 타입별 색상 구분

• 🟢 일반 페이지: 초록색 (예: /about, /contact)
• 🔵 동적 라우트: 파란색 (예: /user/[id], /blog/[...slug])
• 🟠 API 라우트: 주황색 (예: /api/users, /api/auth)

🔗 연결 관계 표시

• 파란색 화살표: router.push() 네비게이션
• 빨간색 화살표: router.replace() 네비게이션
• 초록색 화살표: <Link> 컴포넌트 연결

🖱️ 인터랙티브 기능

• 줌/팬: 마우스 휠과 드래그로 확대/축소 및 이동
• 엣지 클릭: 연결선을 클릭하면 소스 코드 정보 표시
• 자동 레이아웃: 계층적 구조로 자동 정렬

📁 지원하는 프로젝트 구조

Pages Router (Next.js 12 이하)

pages/
├── index.js          → /
├── about.js          → /about
├── user/
│   ├── index.js      → /user
│   └── [id].js       → /user/[id]
└── api/
    └── users.js      → /api/users

App Router (Next.js 13+)

app/
├── page.js           → /
├── about/
│   └── page.js       → /about
├── user/
│   ├── page.js       → /user
│   └── [id]/
│       └── page.js   → /user/[id]
└── api/
    └── users/
        └── route.js  → /api/users

🔍 감지되는 네비게이션 패턴

도구는 다음과 같은 코드 패턴을 자동으로 감지합니다:

// router.push() 호출
import { useRouter } from "next/router";
const router = useRouter();
router.push("/dashboard");

// Link 컴포넌트
import Link from "next/link";
<Link href="/profile">프로필</Link>;

// router.replace() 호출
router.replace("/login");

⚙️ 요구사항

• Node.js: 14.0.0 이상
• Next.js 프로젝트: Pages Router 또는 App Router
• 브라우저: 모던 브라우저 (Chrome, Firefox, Safari, Edge)

📝 예제 출력

도구 실행 후 생성되는 HTML 파일을 브라우저에서 열면:

🗺️  Next.js 라우트 맵 생성 중...
📁 프로젝트 경로: ./my-next-app
🎨 테마: light
📊 출력 형식: web
시각화 파일 생성: ./my-next-app/route-visualizer.html

🛠️ 개발자 정보

프로젝트 구조

next-route-map/
├── src/
│   ├── cli/           # CLI 명령어 처리
│   ├── parser/        # 라우트 파싱 엔진
│   └── types/         # TypeScript 타입 정의
├── dist/              # 빌드된 파일
└── example-next/      # 테스트용 Next.js 프로젝트

기술 스택

• TypeScript: 타입 안전성
• Commander.js: CLI 프레임워크
• Glob: 파일 패턴 매칭
• Cytoscape.js: 그래프 시각화

🤝 기여하기

1. 이 저장소를 포크합니다
2. 기능 브랜치를 생성합니다 (git checkout -b feature/amazing-feature)
3. 변경사항을 커밋합니다 (git commit -m 'Add amazing feature')
4. 브랜치에 푸시합니다 (git push origin feature/amazing-feature)
5. Pull Request를 생성합니다

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

🐛 버그 리포트 & 기능 요청

문제가 발생하거나 새로운 기능을 제안하고 싶으시면 GitHub Issues에 등록해 주세요.

📚 관련 프로젝트

• Next.js - React 프레임워크
• Cytoscape.js - 그래프 시각화 라이브러리
• webpack-bundle-analyzer - 번들 분석 도구 (영감을 받은 프로젝트)

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