> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel-labs/portless/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> Guidelines for contributing to Portless CLI development

## 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

```bash theme={null}
# 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:

```bash theme={null}
pnpm build
```

This uses Turborepo to build packages in dependency order.

### Run Tests

Portless has a comprehensive test suite:

```bash theme={null}
# 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

```bash theme={null}
# 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:
   ```bash theme={null}
   pnpm build
   ```

2. Link it globally:
   ```bash theme={null}
   cd packages/portless
   npm link
   ```

3. Use it in any project:
   ```bash theme={null}
   portless run next dev
   ```

4. After changes, rebuild and the linked version will update:
   ```bash theme={null}
   pnpm build
   ```

### Debugging

For debugging the proxy server:

```bash theme={null}
# 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:

```bash theme={null}
# 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:
  ```bash theme={null}
  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:**
   ```bash theme={null}
   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:**
   ```bash theme={null}
   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:**

```markdown theme={null}
## 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:

```bash theme={null}
# 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:
   ```bash theme={null}
   cd packages/portless
   npm publish
   ```

## Getting Help

* **Issues:** [GitHub Issues](https://github.com/mattdanielmurphy/portless/issues)
* **Discussions:** [GitHub Discussions](https://github.com/mattdanielmurphy/portless/discussions)
* **Documentation:** [https://port1355.dev](https://port1355.dev)

## 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!