Skip to content

Portless

포트 번호를 이름 기반 .localhost URL로 대체하는 도구

About

  • 로컬 개발시 포트 충돌 및 몇번 포트를 썼는지 기억해야 하는 고통을 해결해주는 Vercel Labs의 오픈소스 유틸
  • 각 개발 서버에 고유한 앱.localhost 서브도메인을 부여해, 사람과 AI 에이전트 모두가 인식 가능한 URL 체계 제공
  • next dev 로 실행하면 http://localhost:3000 이어서 3000을 기억해야 하지만
  • portless myapp next dev 실행 시 http://myapp.localhost:1355 형태로 접근 가능
  • portless api.myapp pnpm start 같이 실행하면 http://api.myapp.localhost:1355 로 서브 도메인 접근도 지원
  • 프록시 기반 구조로 동작하며, portless proxy가 중앙에서 요청을 라우팅
    • 앱 실행 시 자동으로 프록시가 시작되고, 각 앱은 임의의 포트(4000–4999)에 할당
    • 대부분의 프레임워크(Next.js, Express, Nuxt 등)는 PORT 환경변수를 자동 인식
    • Vite, Astro 등 일부 프레임워크에는 자동 플래그 주입 기능으로 호환성 확보
  • HTTP/2 및 HTTPS 지원으로 빠른 페이지 로드와 안전한 로컬 통신 구현
    • 자체 인증서 생성 및 시스템 신뢰 저장소 등록 자동화
    • --cert, --key 옵션으로 사용자 지정 인증서도 적용 가능
  • 명령어 중심의 CLI 인터페이스 제공
    • portless <name> <cmd> : 지정 이름으로 앱 실행
    • portless list : 활성 라우트 목록 표시
    • portless proxy start/stop : 프록시 제어
    • PORTLESS=0 환경변수로 프록시 우회 실행 가능
  • 상태 관리 디렉터리를 통해 라우트 및 PID 정보를 저장
    • 일반 사용자 모드에서는 ~/.portless, 루트 모드에서는 /tmp/portless 사용
    • PORTLESS_STATE_DIR로 경로 재정의 가능
  • Vite, webpack-dev-server 등에서 API 프록시 설정 시 Host 헤더 재작성 필요
    • 잘못된 설정 시 508 Loop Detected 응답으로 문제 안내
  • Node.js 20 이상, macOS 및 Linux 환경 지원
  • pnpm + Turborepo 기반 모노레포 구조
  • Apache-2.0 라이선스, TypeScript(약 74%) 코드베이스

See also

Favorite site