use portless (#133)

AGENTS.md

@@ -27,6 +27,26 @@ This ensures we don't install outdated versions that may have incompatible types
 - Do not use emojis in code or UI
 - Use shadcn CLI to add shadcn/ui components: `pnpm dlx shadcn@latest add <component>`
 
+## Dev Servers
+
+All apps and examples with dev servers use [portless](https://github.com/vercel-labs/portless) to avoid hardcoded ports. Portless assigns random ports and exposes each app via `.localhost` URLs.
+
+Naming convention:
+- Main web app: `json-render` → `json-render.localhost:1355`
+- Examples: `[name]-demo.json-render` → `[name]-demo.json-render.localhost:1355`
+
+When adding a new example that runs a dev server, wrap its `dev` script with `portless <name>`:
+
+```json
+{
+  "scripts": {
+    "dev": "portless my-example-demo.json-render next dev --turbopack"
+  }
+}
+```
+
+Do **not** add `--port` flags -- portless handles port assignment automatically. Do **not** add portless as a project dependency; it must be installed globally.
+
 ## Workflow
 
 - Run `pnpm type-check` after each turn to ensure type safety

README.md

@@ -343,9 +343,9 @@ pnpm install
 pnpm dev
 ```
 
-- http://localhost:3000 - Docs & Playground
-- http://localhost:3001 - Example Dashboard
-- http://localhost:3002 - Remotion Video Example
+- http://json-render.localhost:1355 - Docs & Playground
+- http://dashboard-demo.json-render.localhost:1355 - Example Dashboard
+- http://remotion-demo.json-render.localhost:1355 - Remotion Video Example
 - Chat Example: run `pnpm dev` in `examples/chat`
 - React Native example: run `npx expo start` in `examples/react-native`
 

apps/web/README.md

@@ -14,7 +14,7 @@ pnpm dev
 bun dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Open [http://json-render.localhost:1355](http://json-render.localhost:1355) with your browser to see the result.
 
 You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
 

apps/web/app/(main)/docs/code-export/page.mdx

@@ -135,6 +135,6 @@ Run the dashboard example and click "Export Project" to see code generation in a
 ```bash
 cd examples/dashboard
 pnpm dev
-# Open http://localhost:3001
+# Open http://dashboard-demo.json-render.localhost:1355
 # Generate a widget, then click "Export Project"
 ```

apps/web/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "license": "Apache-2.0",
   "scripts": {
-    "dev": "next dev --turbopack",
+    "dev": "portless json-render next dev --turbopack",
     "build": "next build",
     "start": "next start",
     "lint": "eslint --max-warnings 0",

examples/chat/package.json

@@ -4,7 +4,7 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "dev": "next dev --turbopack",
+    "dev": "portless chat-demo.json-render next dev --turbopack",
     "build": "next build",
     "start": "next start",
     "lint": "eslint --max-warnings 0",

examples/dashboard/package.json

@@ -4,7 +4,7 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "dev": "next dev --turbopack",
+    "dev": "portless dashboard-demo.json-render next dev --turbopack",
     "build": "next build",
     "start": "next start",
     "lint": "eslint --max-warnings 0",

examples/no-ai/package.json

@@ -4,7 +4,7 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "dev": "next dev --turbopack --port 3003",
+    "dev": "portless no-ai-demo.json-render next dev --turbopack",
     "build": "next build",
     "start": "next start",
     "lint": "eslint --max-warnings 0",

examples/react-pdf/package.json

@@ -4,7 +4,7 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "dev": "next dev --turbopack --port 3005",
+    "dev": "portless react-pdf-demo.json-render next dev --turbopack",
     "build": "next build",
     "start": "next start",
     "check-types": "tsc --noEmit"

examples/remotion/package.json

@@ -4,7 +4,7 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "dev": "next dev --turbopack --port 3002",
+    "dev": "portless remotion-demo.json-render next dev --turbopack",
     "build": "next build",
     "start": "next start",
     "check-types": "tsc --noEmit"

examples/stripe-app/api/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "next dev --port 3001",
+    "dev": "portless stripe-api-demo.json-render next dev",
     "build": "next build",
     "start": "next start --port 3001"
   },

examples/stripe-app/drawer-app/src/lib/config.ts

@@ -1 +1,2 @@
-export const API_GENERATE_URL = "http://localhost:3001/api/generate";
+export const API_GENERATE_URL =
+  "http://stripe-api-demo.json-render.localhost:1355/api/generate";

examples/stripe-app/fullpage-app/src/lib/config.ts

@@ -1 +1,2 @@
-export const API_GENERATE_URL = "http://localhost:3001/api/generate";
+export const API_GENERATE_URL =
+  "http://stripe-api-demo.json-render.localhost:1355/api/generate";