portless: ポート番号を名前付きローカルURLに置き換える

portlessが置き換えるもの

portlessはローカル開発のURLにおけるポート番号を、安定した名前付きアドレスに置き換えます。アプリがhttp://localhost:3000で実行されていることを覚えておく代わりに、https://myapp.localhostを得られます。このプロジェクトは人間とエージェントの両方のために機能すると説明されており、名前付きURLは人間が入力しやすく、自動化ツールが参照しやすいことを意図しています。READMEは典型的な変更を示しています: next devはportless run next devになり、出力URLは指定したアプリ名に基づきます。

インストールとシステム要件

npm install -g portlessでグローバルインストールするか、npm install -D portlessでプロジェクトの開発依存関係としてインストールします。READMEはプロジェクトがpre-1.0であると述べており、プロジェクトごとのインストールでは貢献者ごとに異なるバージョンが実行される可能性があり、状態ディレクトリの形式はリリース間で変更される可能性があり、portless trustを再実行する必要があるかもしれません。記載されている要件はNode.js 24+とmacOS、Linux、Windowsです。Tailscaleとngrok CLIはオプションであり、共有機能にのみ必要です。

設定: portless.jsonとpackage.jsonキー

素のportlessはpackage.jsonのdevスクリプトをプロキシ経由で実行し、アプリ名をパッケージ名、gitルート、またはディレクトリから推測します。nameフィールドを含むportless.jsonファイルで名前を上書きできます。スクリプトのデフォルトはdevです。モノレポの場合、リポジトリルートの1つのportless.jsonがすべてのワークスペースパッケージをカバーし、pnpm-workspace.yamlまたはpackage.jsonのworkspacesフィールドからパッケージを検出します。appsマップはパッケージごとの名前の上書きを可能にし、ホスト名は<package>.<project>.localhostの規則に従います。パッケージがプロジェクト名と一致する場合を除きます。代わりに、package.jsonの"portless"キーで名前やアプリごとのオプションを設定でき、portless.jsonエントリより優先されますが、CLIフラグで上書きされます。

名前付きルート、サブドメイン、ワークツリー

portlessは各アプリに4000-4999の範囲の空きポートを割り当て、プロキシに登録します。portless api.myapp pnpm startのように名前とコマンドを指定すると、https://api.myapp.localhostが得られます。デフォルトでは明示的に登録されたサブドメインのみがルーティングされ、--wildcardは任意のサブドメインが親アプリにフォールバックすることを許可します。Gitワークツリーは自動的に検出されます: リンクされたワークツリーはブランチ名をサブドメインとして前置し、各ワークツリーは追加設定なしで独自のURLを持ちます。--nameを使用すると、ワークツリーのプレフィックスを維持しながら基本名を上書きできます。

HTTPS、ローカルCA、カスタムTLD

デフォルトでHTTPSとHTTP/2が有効です。初回実行時にportlessはローカルCAを生成し、それを信頼し、ポート443にバインドし、macOSとLinuxではsudoで自動昇格します。--no-tlsで平文HTTPを使用できます。プロキシはアプリを実行すると自動起動し、環境変数で上書きされない限り、最新の実行の設定を再利用します。カスタムTLDは--tldでサポートされ、例えば.testなどがあり、プロキシはルートホスト名のために/etc/hostsを自動同期します。dev.example.comのようなマルチセグメントTLDも許可され、OAuthリダイレクトURIとクッキーを本番と一貫させることができます。READMEは.testを推奨し、.localと.devについて特定の技術的理由から警告しています。

開発サーバーの共有

portlessには3つの共有モードがあります。LANモード（--lan）はプロキシをすべてのインターフェースにバインドし、mDNSを使用してローカルネットワーク上に.local名を公開し、LAN IPを自動検出します。Tailscale共有（--tailscale）は各アプリをtailnet上の独自のHTTPSポートにマウントし、既存のTailscale HTTPS証明書を使用します。Funnel（--funnel）はTailscale Funnelを介してアプリをパブリックインターネットに公開します。ngrok共有（--ngrok）はngrokを通じて公開URLを作成します。各モードには独自の前提条件があります: Tailscale CLIとHTTPS証明書の有効化、ngrok CLIと認証、LANモード用のmDNSツール（Linuxではavahi-utils）。PORTLESS_LAN=1のような環境変数でモードをデフォルトにできます。

運用コマンドとクリーンアップ

コマンドセットには、名前を推測するportless run、静的ルートのportless alias、アクティブなルートを表示するportless list、診断のportless doctor、CAをインストールするportless trust、すべての状態と信頼エントリを削除するportless clean、クラッシュしたセッションの孤児プロセスを強制終了するportless pruneが含まれます。プロキシ制御コマンドもあります: portless proxy start、stop、および--port、--no-tls、--foreground、--wildcardなどのオプション。portless service installでプロキシをOS起動サービスとしてインストールでき、launchd、systemd、またはタスクスケジューラを使用します。READMEにはプロキシ設定を上書きする環境変数と、PORTやPORTLESS_URLなど子プロセスに注入される変数のリストが含まれています。1回の実行でportlessを無効にするには、PORTLESS=0を設定します。

編集部の結論

portless は複数のローカル開発サービスを名前付きHTTPSで開きたいチームに適しています。CIや独自のCLI構文、443を使えない環境では自動注入が止まる可能性があります。最初に portless myapp next dev と portless trust を実行し、package.json の dev script、PORT、~/.portless の登録状態を確認するのが判断の起点です。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes