Skip to content

feat: add --path flag for path-based routing#165

Open
rqbazan wants to merge 4 commits intovercel-labs:mainfrom
rqbazan:feat/path-based-routing
Open

feat: add --path flag for path-based routing#165
rqbazan wants to merge 4 commits intovercel-labs:mainfrom
rqbazan:feat/path-based-routing

Conversation

@rqbazan
Copy link
Copy Markdown

@rqbazan rqbazan commented Mar 27, 2026

Summary

  • Add --path <prefix> flag to route multiple apps under one hostname by URL path prefix
  • The proxy uses longest-prefix matching to dispatch requests to the correct backend
  • Full request path is forwarded unchanged -- backends handle their own base path
  • Also available via PORTLESS_PATH env var
  • Fix: pass --wildcard flag when auto-starting proxy (was missing from runApp)
portless myapp vite dev                  # serves /
portless myapp --path /api pnpm start    # serves /api/*
portless myapp --path /docs next dev     # serves /docs/*

Useful for local API gateways, microfrontends, monorepos, or any setup where services share a domain.

Implementation Details

  • RouteInfo gains an optional pathPrefix field. Route identity becomes hostname + pathPrefix -- same hostname with different paths coexist without conflict.
  • findRoute() performs two-stage matching: hostname first (exact, then wildcard fallback), then longest path prefix among candidates. A matchesPathPrefix() helper enforces / boundary checks (/api matches /api/users but not /api-v2).
  • --path is recognized in parseRunArgs, parseAppArgs, and auxiliary commands (get, alias, list).
  • Backward compatible: routes without --path work exactly as before. Existing routes.json files are read without migration.

Test plan

  • pnpm test -- 355 tests pass (35+ new covering path routing, route store, CLI parsing, utils)
  • pnpm typecheck -- clean
  • pnpm lint -- clean
  • pnpm format:check -- clean
  • pnpm build -- builds including docs site
  • Manual: run three apps under one hostname with different --path prefixes, verify requests route correctly
  • Manual: wildcard subdomain + path routing works together
  • Manual: PORTLESS_WILDCARD=1 correctly passed on proxy auto-start

@vercel
Copy link
Copy Markdown

vercel bot commented Mar 27, 2026

@rqbazan is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

Add `--path <prefix>` flag so multiple services can share one hostname
and route by URL path prefix using longest-prefix matching.

  portless myapp vite dev                    # serves /
  portless myapp --path /api pnpm start      # serves /api/*
  portless myapp --path /docs next dev       # serves /docs/*

Useful for local API gateways, microfrontends, monorepos, or any setup
where services share a domain. The full request path is forwarded to
the backend unchanged.

Changes:
- Add optional `pathPrefix` field to RouteInfo interface
- Add `normalizePathPrefix()` helper and extend `formatUrl()` with path
- Update RouteStore for pathPrefix-aware add/remove/conflict detection
- Update `findRoute()` with two-stage matching: hostname then longest path prefix
- Add `--path` flag to `parseRunArgs` and `parseAppArgs`
- Wire pathPrefix through `runApp`, `handleRunMode`, `handleNamedMode`
- Update `list`, `get`, `alias` commands with path prefix support
- Update 404 page to show path prefixes in active routes list
- Add `PORTLESS_PATH` env var as alternative to the flag
- Update README, SKILL.md, and CLI help text

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@rqbazan rqbazan force-pushed the feat/path-based-routing branch from 667a8b9 to 1286edf Compare March 31, 2026 18:36
@rqbazan
Copy link
Copy Markdown
Author

rqbazan commented Apr 1, 2026

Hi @ctate , I wanted to follow up on this PR. It's been a few days and I'd love to keep things moving — would you be able to take a look when you have a moment? Happy to make any changes if needed. Thanks!

rqbazan and others added 3 commits April 6, 2026 07:32
Resolve conflicts combining path-based routing with LAN mode support.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant