Skip to main content

​
Development Setup

Portless uses a pnpm workspace monorepo with Turborepo for build orchestration. The publishable package lives in packages/portless/.

​
Prerequisites

  • Node.js 20 or higher
  • pnpm (install via npm install -g pnpm)
  • Git
  • macOS or Linux (Windows support may work but is not officially supported)

​
Clone and Install

# Clone the repository
git clone https://github.com/mattdanielmurphy/portless.git
cd portless

# Install all dependencies
pnpm install

​
Build

Build all packages in the monorepo: 
pnpm build
This uses Turborepo to build packages in dependency order.

​
Run Tests

Portless has a comprehensive test suite: 
# Run all tests
pnpm test

# Run tests with coverage report
pnpm test:coverage

# Run tests in watch mode (for development)
pnpm test:watch

​
Linting and Type Checking

# Lint all packages
pnpm lint

# Type-check all packages
pnpm typecheck

# Format code with Prettier
pnpm format

​
Local Development

To test your changes locally:
  1. Build the package: 
    pnpm build
  2. Link it globally: 
    cd packages/portless
npm link
  3. Use it in any project: 
    portless run next dev
  4. After changes, rebuild and the linked version will update: 
    pnpm build

​
Debugging

For debugging the proxy server: 
# Run in foreground to see all logs
portless proxy start --foreground

# Check the proxy log file
cat ~/.portless/proxy.log

# Check active routes
portless list

​
Monorepo Structure

portless/
├── packages/
│   └── portless/           # Main CLI package (publishable)
│       ├── src/
│       │   ├── cli.ts      # CLI entry point and command parsing
│       │   ├── proxy.ts    # HTTP/HTTPS proxy server logic
│       │   ├── routes.ts   # Route storage and management
│       │   ├── certs.ts    # TLS certificate generation
│       │   ├── hosts.ts    # /etc/hosts file management
│       │   ├── auto.ts     # Project name inference and worktree detection
│       │   ├── cli-utils.ts # CLI helper functions
│       │   ├── utils.ts    # General utilities
│       │   └── types.ts    # TypeScript type definitions
│       ├── package.json
│       └── tsconfig.json
├── skills/                 # Agent skills for AI coding assistants
│   └── portless/
│       └── SKILL.md        # Agent instructions for using portless
├── turbo.json              # Turborepo configuration
├── pnpm-workspace.yaml     # pnpm workspace config
├── CHANGELOG.md            # Version history
├── README.md               # Main documentation
└── AGENTS.md               # Rules for AI agents working on the repo

​
Package Manager Rules

Portless uses pnpm for all package management: 
# Add a dependency
pnpm add <package>

# Add a dev dependency
pnpm add -D <package>

# Install all dependencies
pnpm install

# Run scripts
pnpm build
pnpm test
Exception: Global install instructions for end users should use npm install -g since it’s universal and most developers have npm by default.

​
Making Changes

​
Code Style

  • No emojis anywhere in the codebase (code, comments, output, docs)
  • Use TypeScript for all source files
  • Follow the existing code style (enforced by ESLint and Prettier)
  • Write clear, concise comments for complex logic

​
Testing

  • Add tests for new features
  • Update existing tests when changing behavior
  • Ensure all tests pass before submitting a PR: 
    pnpm test

​
Documentation

When a change affects how humans or agents use portless, update all three of these:
  1. README.md - User-facing documentation
  2. skills/portless/SKILL.md - Agent skill for AI coding assistants
  3. packages/portless/src/cli.ts - --help output
This ensures consistency across all documentation surfaces.

​
Pull Request Guidelines

​
Before Submitting

  1. Test your changes: 
    pnpm test
pnpm typecheck
pnpm lint
  2. Update the changelog: Add a description of your changes to CHANGELOG.md under the “Unreleased” section (or create one if it doesn’t exist).
  3. Update documentation if needed (see above).
  4. Build successfully: 
    pnpm build

​
PR Title Format

Use conventional commit format:
  • feat: add support for custom proxy headers
  • fix: resolve certificate trust issue on Arch Linux
  • docs: update installation instructions
  • refactor: simplify route matching logic
  • test: add e2e tests for worktree detection

​
PR Description

Include:
  1. What - What changes did you make?
  2. Why - Why were these changes necessary?
  3. How - How did you implement the solution?
  4. Testing - What testing did you do?
Example: 
## What
Adds support for custom proxy headers via `--header` flag.

## Why
Users need to pass custom headers to backend services for
authentication or routing purposes.

## How
Extended the proxy request logic to include headers from a new
`--header` flag that can be specified multiple times.

## Testing
- Added unit tests for header parsing
- Tested manually with Next.js and Express apps
- Verified headers appear in backend logs

​
Review Process

  1. A maintainer will review your PR
  2. Address any feedback or requested changes
  3. Once approved, a maintainer will merge your PR
  4. Your changes will be included in the next release

​
Commit Messages

Use clear, descriptive commit messages: 
# Good
git commit -m "fix: handle ECONNREFUSED gracefully in proxy"
git commit -m "feat: add --app-port flag for fixed port assignment"
git commit -m "docs: document Safari DNS workaround"

# Avoid
git commit -m "fix bug"
git commit -m "update code"
git commit -m "changes"

​
Release Process

(For maintainers)
  1. Update version in packages/portless/package.json
  2. Move “Unreleased” section in CHANGELOG.md to a new version section
  3. Commit changes: git commit -m "chore: release v0.x.x"
  4. Create git tag: git tag v0.x.x
  5. Push changes and tag: git push && git push --tags
  6. Publish to npm: 
    cd packages/portless
npm publish

​
Getting Help

​
Code of Conduct

Be respectful and considerate of others. We’re all here to make portless better.
  • Be welcoming and inclusive
  • Respect differing viewpoints and experiences
  • Accept constructive criticism gracefully
  • Focus on what’s best for the community
  • Show empathy towards other community members
Thank you for contributing to Portless!

Build docs developers (and LLMs) love

Get started for freeTalk to us