Portfinder

A simple CLI tool to find available ports for monorepo development with multiple git worktrees.

Platform Support

⚠️ Mac/Linux only - This tool requires shell command substitution support ($()), which is not available in Windows cmd.exe.

Installation

Install in your monorepo root:

npm install portfinder
# or
pnpm add portfinder

Usage

Use command substitution to set the PORT environment variable:

PORT=$(portfinder 3000) next dev

In package.json scripts

{
  "scripts": {
    "dev": "PORT=$(portfinder 3000) next dev --turbopack"
  }
}

With multiple environment variables

{
  "scripts": {
    "dev": "PORT=$(portfinder 3000) API_PORT=$(portfinder 4000) node server.js"
  }
}

Monorepo setup with different base ports

// apps/web/package.json
{
  "scripts": {
    "dev": "PORT=$(portfinder 3000) next dev"
  }
}

// apps/admin/package.json
{
  "scripts": {
    "dev": "PORT=$(portfinder 3100) next dev"
  }
}

// apps/api/package.json
{
  "scripts": {
    "dev": "PORT=$(portfinder 3200) node server.js"
  }
}

How it works

1. When you run portfinder 3000, it checks if port 3000 is available
2. If port 3000 is taken, it automatically finds the next available port (3001, 3002, etc.)
3. The command outputs only the port number to stdout
4. Shell command substitution captures this output and sets it as an environment variable

Example workflow with git worktrees

When running multiple worktrees of the same monorepo:

• Worktree 1: pnpm dev → apps run on ports 3000, 3100, 3200
• Worktree 2: pnpm dev → apps automatically use ports 3001, 3101, 3201
• Worktree 3: pnpm dev → apps automatically use ports 3002, 3102, 3202

No port conflicts, no manual configuration needed!

License

MIT