1. 개요 (Overview)

nherd는 현재 프로젝트에서 npm run dev로 시작하는 Vite 또는 Astro 개발 서버를 Laravel Herd의 https://[프로젝트 폴더명].test 주소로 연결하는 macOS 명령줄 도구입니다. 실제로 선택된 포트를 찾아 프록시를 등록하고, 종료할 때 개발 서버 프로세스와 프록시를 정리합니다.
"개발 서버의 포트를 직접 찾고 Herd 프록시를 설정하는 일을 한 번의 명령으로 처리합니다."
npm install -g nherdnherd run dev사용 환경은 macOS, Node.js 24 이상, npm, Laravel Herd입니다. 프로젝트 폴더 이름이 .test 주소 규칙에 맞아야 하고, 개발 서버가 해당 호스트를 허용하도록 설정해야 합니다. 설치와 배포 정보는 npm 패키지 페이지에서 확인할 수 있습니다.
소개 페이지는 nherd.repl.net에서 볼 수 있습니다.
2. 사용된 표준 문서 (Documents Used)
프로젝트는 REPL Works 표준 문서로 목적, 기술 제약, 구성과 작업 순서를 정리합니다.
- PRODUCT_SPEC.md: 명령, 입력, 출력, 오류와 제품 요구사항
- TECH_STACK.md: Node.js, TypeScript, 테스트와 배포 제약
- ARCHITECTURE.md: 구성 요소, 책임 경계와 종료 처리 흐름
- TASKS.md: 구현 작업과 수락 기준
- AGENTS.md: AI 작업 절차와 공통 규칙
3. 적용 워크플로 (Workflow Usage)
TASKS.md의 작업마다 내부 로직 단위 테스트와 필요한 실제 Herd 통합 검증을 정의합니다. 프록시 등록 전에 포트 탐지와 준비 상태를 확인하고, 종료 시에는 개발 서버 프로세스가 정리된 뒤 등록한 프록시를 해제하도록 설계했습니다.
4. 사용 기술 (Tools Used)
- Node.js 24, TypeScript, npm: macOS용 CLI 구현과 배포
- Laravel Herd CLI: HTTPS
.test도메인 프록시 등록과 해제 - Vite, Astro: 연결 대상 개발 서버
- Vitest, Playwright: 단위 테스트와 브라우저 기반 통합 검증
- Biome, GitHub Actions: 코드 검사와 CI
5. 학습된 레슨 (Lessons Learned)
종료 경로도 제품 동작의 일부입니다. Ctrl+C, SIGTERM, 개발 서버 종료, 프록시 오류를 각각 다루고, 어떤 경로로 끝나더라도 개발 서버 프로세스가 남지 않으며 등록한 프록시가 정리되는지 검증합니다.