chore: add portless support for easier dev

Author: haritabh-z01

README.md

@@ -55,7 +55,7 @@ cd refref
 docker-compose up
 ```
 
-That's it! 🎉 The webapp portal will be available at http://localhost:3000
+That's it! 🎉 The webapp portal will be available at http://localhost:3000.
 
 Docker Compose automatically handles:
 
@@ -73,6 +73,7 @@ If you prefer running RefRef locally without Docker:
 - Node.js 20+
 - pnpm 10.15.0
 - PostgreSQL database
+- [portless](https://github.com/vercel-labs/portless) (`npm install -g portless`)
 
 #### Installation
 
@@ -96,7 +97,17 @@ pnpm -F @refref/webapp db:seed
 pnpm dev
 ```
 
-The webapp will be available at http://localhost:3000
+Each app gets a stable `.localhost` URL via [portless](https://github.com/vercel-labs/portless):
+
+| App    | URL                                 |
+| ------ | ----------------------------------- |
+| Webapp | http://refref-webapp.localhost:1355 |
+| WWW    | http://refref-www.localhost:1355    |
+| API    | http://refref-api.localhost:1355    |
+| Refer  | http://refref-refer.localhost:1355  |
+| Acme   | http://refref-acme.localhost:1355   |
+
+> Portless is a global CLI tool (`npm install -g portless`). The proxy auto-starts when you run `pnpm dev`. To bypass portless, set `PORTLESS=0 pnpm dev`.
 
 ### Environment Variables
 
@@ -109,7 +120,7 @@ The webapp will be available at http://localhost:3000
 
 - `GOOGLE_CLIENT_ID` & `GOOGLE_CLIENT_SECRET` - For Google OAuth authentication
 - `RESEND_API_KEY` - For sending emails via Resend
-- `BETTER_AUTH_URL` - Authentication URL (defaults to http://localhost:3000)
+- `BETTER_AUTH_URL` - Authentication URL (defaults to http://refref-webapp.localhost:1355)
 
 ### Development Commands
 

apps/acme/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "description": "Test application for RefRef integration testing and demos",
   "scripts": {
-    "dev": "next dev --port 3003",
+    "dev": "portless refref-acme -- next dev",
     "build": "next build",
     "start": "next start --port 3003"
   },

apps/api/.env.example

@@ -8,4 +8,5 @@ LOG_LEVEL=info
 DATABASE_URL="postgresql://postgres:postgres@localhost:5432/refref"
 
 # Referral Configuration
-REFERRAL_HOST_URL="http://localhost:3002"
+# With portless: http://refref-refer.localhost:1355 | Without: http://localhost:3002
+REFERRAL_HOST_URL="http://refref-refer.localhost:1355"

apps/api/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "infisical run --env=dev -- tsx watch src/index.ts || tsx watch src/index.ts",
+    "dev": "portless refref-api -- infisical run --env=dev -- tsx watch src/index.ts || portless refref-api -- tsx watch src/index.ts",
     "build": "tsc",
     "start": "node dist/index.js",
     "test": "infisical run --env=dev -- vitest run || vitest run",

apps/e2e/.env.example

@@ -5,11 +5,11 @@ TEST_PREFIX=e2e_test_           # Prefix for all test data
 CLEANUP_ON_FAILURE=false       # Clean up test data even on failure
 VIDEO_ON_FAILURE=true          # Record video on test failure
 
-# Server URLs
-WEBAPP_URL=http://localhost:3000
-API_URL=http://localhost:3001
-REFER_URL=http://localhost:3002
-ACME_URL=http://localhost:3003
+# Server URLs (portless)
+WEBAPP_URL=http://refref-webapp.localhost:1355
+API_URL=http://refref-api.localhost:1355
+REFER_URL=http://refref-refer.localhost:1355
+ACME_URL=http://refref-acme.localhost:1355
 ASSETS_URL=http://localhost:8787
 
 # Database (already set up locally, will be seeded as needed)
@@ -33,7 +33,7 @@ REFEREE_EMAIL=jane.smith@example.com
 
 # Better Auth (for test user creation)
 BETTER_AUTH_SECRET=test-auth-secret-for-e2e
-BETTER_AUTH_URL=http://localhost:3000
+BETTER_AUTH_URL=http://refref-webapp.localhost:1355
 
 # Safety Flags
 DRY_RUN=false                  # Run in dry-run mode (no actual changes)

apps/refer/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "infisical run --env=dev -- tsx watch src/index.ts || tsx watch src/index.ts",
+    "dev": "portless refref-refer -- infisical run --env=dev -- tsx watch src/index.ts || portless refref-refer -- tsx watch src/index.ts",
     "build": "tsc",
     "start": "node dist/index.js",
     "test": "infisical run --env=dev -- vitest run || vitest run",

apps/webapp/.env.example

@@ -13,12 +13,14 @@ DATABASE_URL="postgresql://postgres:postgres@localhost:5432/refref"
 BETTER_AUTH_SECRET="your-secret-key-here-change-in-production"
 
 # Authentication URL (OPTIONAL)
-# The URL where Better Auth is hosted (defaults to http://localhost:3000)
-BETTER_AUTH_URL="http://localhost:3000"
+# The URL where Better Auth is hosted
+# With portless: http://refref-webapp.localhost:1355 | Without: http://localhost:3000
+BETTER_AUTH_URL="http://refref-webapp.localhost:1355"
 
 # Application URL (OPTIONAL)
 # The public URL of your application
-NEXT_PUBLIC_APP_URL="http://localhost:3000"
+# With portless: http://refref-webapp.localhost:1355 | Without: http://localhost:3000
+NEXT_PUBLIC_APP_URL="http://refref-webapp.localhost:1355"
 
 # Google OAuth (OPTIONAL)
 # Required only if you want to enable Google sign-in
@@ -49,6 +51,6 @@ NEXT_PUBLIC_POSTHOG_ENABLED="true"
 
 # External Services (OPTIONAL)
 # URL of the assets CDN for loading widget and attribution scripts
-# In development: http://localhost:3002 (refer server serves scripts dynamically)
+# In development: http://refref-refer.localhost:1355 (refer server serves scripts dynamically)
 # In production: https://assets.refref.ai (Cloudflare Pages CDN)
-NEXT_PUBLIC_ASSETS_URL="http://localhost:3002"
+NEXT_PUBLIC_ASSETS_URL="http://refref-refer.localhost:1355"

apps/webapp/package.json

@@ -11,7 +11,7 @@
     "db:push": "pnpm -F @refref/coredb db:push",
     "db:studio": "pnpm -F @refref/coredb db:studio",
     "db:seed": "pnpm -F @refref/coredb db:seed",
-    "dev": "infisical run --env=dev -- next dev --turbo || next dev --turbo",
+    "dev": "portless refref-webapp -- infisical run --env=dev -- next dev --turbo || portless refref-webapp -- next dev --turbo",
     "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,mdx}\" --cache",
     "format:write": "prettier --write \"**/*.{ts,tsx,js,jsx,mdx}\" --cache",
     "lint": "next lint",

apps/www/package.json

@@ -6,7 +6,7 @@
     "build": "pnpm fetch-content && pnpm build:docs && pnpm lint && next build && pnpm build:sitemap",
     "build:sitemap": "pnpm exec tsx ./scripts/generate-sitemap.mts",
     "build:docs": "node ./scripts/generate-docs.mjs",
-    "dev": "infisical run --env=dev -- next dev || next dev",
+    "dev": "portless refref-www -- infisical run --env=dev -- next dev || portless refref-www -- next dev",
     "start": "next start",
     "postinstall": "fumadocs-mdx",
     "serve": "serve out -p 3000",

package.json

@@ -4,6 +4,8 @@
   "scripts": {
     "build": "turbo run build",
     "dev": "infisical run --env=dev -- turbo run dev || turbo run dev",
+    "portless:list": "portless list",
+    "portless:proxy": "portless proxy start",
     "lint": "turbo run lint",
     "format": "prettier --write \"**/*.{ts,tsx,md}\"",
     "type:check": "turbo run type:check",