use portless

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/a2ui/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "A2UI Integration" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/a2ui")
 
 # A2UI Integration
 

apps/web/app/(main)/docs/adaptive-cards/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Adaptive Cards Integration" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/adaptive-cards")
 
 # Adaptive Cards Integration
 

apps/web/app/(main)/docs/ag-ui/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "AG-UI Integration" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/ag-ui")
 
 # AG-UI Integration
 

apps/web/app/(main)/docs/ai-sdk/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "AI SDK Integration" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/ai-sdk")
 
 # AI SDK Integration
 

apps/web/app/(main)/docs/api/codegen/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "@json-render/codegen API" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/codegen")
 
 # @json-render/codegen
 

apps/web/app/(main)/docs/api/core/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "@json-render/core API" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/core")
 
 # @json-render/core
 

apps/web/app/(main)/docs/api/react-native/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "@json-render/react-native API" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/react-native")
 
 # @json-render/react-native
 

apps/web/app/(main)/docs/api/react-pdf/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "@json-render/react-pdf API" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/react-pdf")
 
 # @json-render/react-pdf
 

apps/web/app/(main)/docs/api/react/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "@json-render/react API" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/react")
 
 # @json-render/react
 

apps/web/app/(main)/docs/api/remotion/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "@json-render/remotion API" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/remotion")
 
 # @json-render/remotion
 

apps/web/app/(main)/docs/api/shadcn/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "@json-render/shadcn API" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/shadcn")
 
 # @json-render/shadcn
 

apps/web/app/(main)/docs/catalog/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Catalog" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/catalog")
 
 # Catalog
 

apps/web/app/(main)/docs/changelog/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Changelog" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/changelog")
 
 # Changelog
 

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

@@ -1,4 +1,5 @@
-export const metadata = { title: "Code Export" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/code-export")
 
 # Code Export
 
@@ -134,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/app/(main)/docs/custom-schema/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Custom Schema & Renderer" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/custom-schema")
 
 # Custom Schema & Renderer
 

apps/web/app/(main)/docs/data-binding/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Data Binding" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/data-binding")
 
 # Data Binding
 

apps/web/app/(main)/docs/generation-modes/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Generation Modes" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/generation-modes")
 
 # Generation Modes
 

apps/web/app/(main)/docs/installation/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Installation" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/installation")
 
 # Installation
 

apps/web/app/(main)/docs/migration/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Migration Guide" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/migration")
 
 # Migration Guide
 

apps/web/app/(main)/docs/openapi/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "OpenAPI Integration" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/openapi")
 
 # OpenAPI Integration
 

apps/web/app/(main)/docs/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Introduction" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs")
 
 # Introduction
 

apps/web/app/(main)/docs/quick-start/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Quick Start" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/quick-start")
 
 # Quick Start
 

apps/web/app/(main)/docs/registry/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Registry" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/registry")
 
 # Registry
 

apps/web/app/(main)/docs/schemas/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Schemas" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/schemas")
 
 # Schemas
 

apps/web/app/(main)/docs/specs/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Specs" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/specs")
 
 # Specs
 

apps/web/app/(main)/docs/streaming/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Streaming" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/streaming")
 
 # Streaming
 

apps/web/app/(main)/docs/validation/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Validation" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/validation")
 
 # Validation
 

apps/web/app/(main)/docs/visibility/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Visibility" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/visibility")
 
 # Visibility
 

apps/web/app/layout.tsx

@@ -61,7 +61,6 @@ export const metadata: Metadata = {
     description:
       "The Generative UI framework. Generate dashboards, widgets, and apps from prompts — safely constrained to components you define.",
     images: ["/og"],
-    creator: "@verabornnot",
   },
   robots: {
     index: true,

apps/web/lib/page-metadata.ts

@@ -0,0 +1,39 @@
+import type { Metadata } from "next";
+import { PAGE_TITLES } from "./page-titles";
+
+const DESCRIPTION =
+  "The Generative UI framework. Generate dashboards, widgets, and apps from prompts — safely constrained to components you define.";
+
+export function pageMetadata(slug: string): Metadata {
+  const title = PAGE_TITLES[slug];
+  if (!title) return {};
+
+  const displayTitle = title.replace(/\n/g, " ");
+  const fullTitle = `${displayTitle} | json-render`;
+  const ogImageUrl = slug ? `/og/${slug}` : "/og";
+
+  return {
+    title: displayTitle,
+    openGraph: {
+      type: "website",
+      locale: "en_US",
+      siteName: "json-render",
+      title: fullTitle,
+      description: DESCRIPTION,
+      images: [
+        {
+          url: ogImageUrl,
+          width: 1200,
+          height: 630,
+          alt: `${displayTitle} - json-render`,
+        },
+      ],
+    },
+    twitter: {
+      card: "summary_large_image",
+      title: fullTitle,
+      description: DESCRIPTION,
+      images: [ogImageUrl],
+    },
+  };
+}

apps/web/lib/page-titles.ts

@@ -42,6 +42,7 @@ export const PAGE_TITLES: Record<string, string> = {
   "docs/api/react-native": "@json-render/react-native API",
   "docs/api/codegen": "@json-render/codegen API",
   "docs/api/remotion": "@json-render/remotion API",
+  "docs/api/shadcn": "@json-render/shadcn API",
 };
 
 /**

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";