feat(cli)!: default dev/start port to 8080 instead of 3000 (#97)

* feat(cli)!: default dev/start port to 8080 instead of 3000

Change the fallback port in `webjs dev` / `webjs start` from 3000 to
8080 (process.env.PORT still wins, so deploys that inject PORT are
unaffected). 3000 is heavily contested locally (Next.js, CRA, Express,
Flask all default there); 8080 collides less for the scaffolded-app
experience.

Also updates the OAuth redirect's no-request fallback origin in
auth.js from localhost:3000 to localhost:8080 so dev OAuth URLs match
the new default.

Scaffolded apps pick this up for free: their package.json scripts stay
`webjs dev` / `webjs start` (no --port), so they inherit the new
default with zero template changes and full cross-platform behavior.

BREAKING: existing apps that relied on the implicit 3000 default will
now serve on 8080 locally after upgrading @webjsdev/cli. Set PORT=3000
or pass --port 3000 to keep the old port.

* docs: update default-port references from 3000 to 8080

Sweep docs, scaffold templates, and package READMEs to reflect the new
8080 default (getting-started, configuration, deployment, websockets,
backend-only, server-actions pages; scaffold .env.example + CONVENTIONS;
scaffold success message; cli/create-webjs/server READMEs; agent-docs;
root README quickstart). Word-boundary match preserves the 30000ms
interval example in the controllers page. The blog's own .env.example
port is left to the dev-ports change.

* fix(server): default startServer port to 8080, matching the CLI

startServer's own `opts.port ?? 3000` fallback was missed when the CLI
default moved to 8080. The CLI always passes an explicit port, so this
only affected programmatic startServer callers and embedders, but it
left an inconsistent 3000 default. Align it with the new 8080 default.

Author: vivek7405

README.md

@@ -52,7 +52,7 @@ TypeScript with zero build step, real SSR with Declarative Shadow DOM.
 # Get started in one command (no global install required)
 npm create webjs@latest my-app   # full-stack (pages + API + components + Prisma/SQLite)
 cd my-app && npm run dev
-# → http://localhost:3000
+# → http://localhost:8080
 
 # Backend-only API
 npm create webjs@latest my-api  -- --template api

agent-docs/built-ins.md

@@ -106,7 +106,7 @@ JWT sessions by default (stateless, scales horizontally). OAuth providers handle
 | `AUTH_GITHUB_ID` / `AUTH_GITHUB_SECRET` | GitHub OAuth (optional) |
 | `SESSION_SECRET` | Cookie session signing |
 | `REDIS_URL` | When set, sessions + rate limit + cache use Redis |
-| `PORT` | Server port (default 3000) |
+| `PORT` | Server port (default 8080) |
 
 ## Scaling to multiple instances
 

docs/app/docs/backend-only/page.ts

@@ -203,7 +203,7 @@ const events = await richFetch('/api/events');
 // events[0].createdAt is a real Date object
 
 // External client (curl, Postman) gets plain JSON automatically
-// curl http://localhost:3000/api/events</pre>
+// curl http://localhost:8080/api/events</pre>
     <p>The <code>json()</code> helper reads the <code>Accept</code> header. If the client sent <code>Accept: application/vnd.webjs+json</code> (as <code>richFetch</code> does), the response is encoded with the webjs serializer. Otherwise, plain <code>application/json</code>. The <code>Vary: Accept</code> header is set automatically.</p>
     <p>For reading request bodies with the same content negotiation, use <code>readBody(req)</code> from <code>@webjsdev/server</code>.</p>
 
@@ -250,7 +250,7 @@ fastify.all('*', async (request, reply) =&gt; {
   reply.send(body);
 });
 
-fastify.listen({ port: 3000 });</pre>
+fastify.listen({ port: 8080 });</pre>
 
     <h2>Comparison with Express/Fastify</h2>
     <p>Here is what webjs gives you compared to a traditional Node.js API framework:</p>
@@ -329,9 +329,9 @@ export async function POST(req: Request) {
 
     <h3>Run it</h3>
     <pre>webjs dev
-# API is live at http://localhost:3000
-# curl http://localhost:3000/api/posts
-# curl http://localhost:3000/__webjs/health</pre>
+# API is live at http://localhost:8080
+# curl http://localhost:8080/api/posts
+# curl http://localhost:8080/__webjs/health</pre>
     <p>No pages, no layouts, no components, no SSR. Just a fast, typed API server with file-based routing.</p>
   `;
 }

docs/app/docs/configuration/page.ts

@@ -9,19 +9,19 @@ export default function Configuration() {
 
     <h2>CLI Options</h2>
     <h3>webjs dev</h3>
-    <pre>webjs dev [--port 3000]</pre>
+    <pre>webjs dev [--port 8080]</pre>
     <ul>
-      <li><code>--port</code>: dev server port (default: <code>3000</code>, or <code>PORT</code> env var)</li>
+      <li><code>--port</code>: dev server port (default: <code>8080</code>, or <code>PORT</code> env var)</li>
       <li>File watching via chokidar (automatic)</li>
       <li>Live reload via SSE (<code>/__webjs/events</code>)</li>
       <li>TypeScript files transformed on the fly</li>
       <li>No cache-busting needed, since module loads are busted per request</li>
     </ul>
 
     <h3>webjs start</h3>
-    <pre>webjs start [--port 3000]</pre>
+    <pre>webjs start [--port 8080]</pre>
     <ul>
-      <li><code>--port</code>: production server port (also honors the <code>PORT</code> env var, default 3000)</li>
+      <li><code>--port</code>: production server port (also honors the <code>PORT</code> env var, default 8080)</li>
       <li>Speaks plain HTTP/1.1. TLS termination + HTTP/2 to the browser is the proxy's job (PaaS edges or nginx/Caddy/Traefik)</li>
       <li>gzip/brotli compression enabled by default</li>
       <li>Static file ETag + Cache-Control headers</li>
@@ -104,7 +104,7 @@ class Checkout extends WebComponent {
 // Option 1: Full server
 await startServer({
   appDir: process.cwd(),
-  port: 3000,
+  port: 8080,
   dev: false,
   compress: true,
   http2: false,

docs/app/docs/deployment/page.ts

@@ -10,10 +10,10 @@ export default function Deployment() {
     <h2>Dev vs Prod</h2>
     <p>webjs has two modes, controlled by the npm script (which wraps the underlying <code>webjs dev</code> / <code>webjs start</code> CLI):</p>
     <pre># Development: live reload, no compression, no caching, verbose errors
-npm run dev -- --port 3000
+npm run dev -- --port 8080
 
 # Production: compression, ETags, cache headers, graceful shutdown
-npm run start -- --port 3000</pre>
+npm run start -- --port 8080</pre>
     <p>Key differences:</p>
     <ul>
       <li><strong>Dev:</strong> chokidar watches your source tree and triggers live reload via SSE. TypeScript files are served with <code>Cache-Control: no-cache</code>. Errors include full stack traces. No compression.</li>
@@ -55,13 +55,13 @@ GET /__webjs/ready     # { "status": "ok" }</pre>
 livenessProbe:
   httpGet:
     path: /__webjs/health
-    port: 3000
+    port: 8080
   initialDelaySeconds: 5
   periodSeconds: 10
 readinessProbe:
   httpGet:
     path: /__webjs/ready
-    port: 3000
+    port: 8080
   initialDelaySeconds: 3
   periodSeconds: 5</pre>
 
@@ -77,10 +77,10 @@ readinessProbe:
     <h2>Pluggable Logger</h2>
     <p>webjs includes a minimal logger that writes structured JSON in production and human-readable lines in development:</p>
     <pre># Dev output:
-[webjs] webjs dev server ready on http://localhost:3000
+[webjs] webjs dev server ready on http://localhost:8080
 
 # Prod output (one JSON line per event):
-{"level":"info","msg":"webjs prod server ready on http://localhost:3000","time":"2026-01-15T10:30:00.000Z"}</pre>
+{"level":"info","msg":"webjs prod server ready on http://localhost:8080","time":"2026-01-15T10:30:00.000Z"}</pre>
     <p>Replace it with your own logger by passing any object with <code>info</code>, <code>warn</code>, and <code>error</code> methods to <code>createRequestHandler</code>:</p>
     <pre>import { createRequestHandler } from '@webjsdev/server';
 import pino from 'pino';
@@ -139,15 +139,15 @@ server.all('*', async (req, res) =&gt; {
   res.end();
 });
 
-server.listen(3000);</pre>
+server.listen(8080);</pre>
 
     <h3>Bun</h3>
     <pre>import { createRequestHandler } from '@webjsdev/server';
 
 const app = await createRequestHandler({ appDir: process.cwd(), dev: false });
 
 Bun.serve({
-  port: 3000,
+  port: 8080,
   fetch: (req) =&gt; app.handle(req),
 });</pre>
 
@@ -156,12 +156,12 @@ Bun.serve({
 
 const app = await createRequestHandler({ appDir: Deno.cwd(), dev: false });
 
-Deno.serve({ port: 3000 }, (req) =&gt; app.handle(req));</pre>
+Deno.serve({ port: 8080 }, (req) =&gt; app.handle(req));</pre>
 
     <h2>Environment Variables</h2>
     <p>webjs reads the following environment variables:</p>
     <ul>
-      <li><strong>PORT</strong>: server port (default: 3000). Overridden by <code>--port</code> CLI flag.</li>
+      <li><strong>PORT</strong>: server port (default: 8080). Overridden by <code>--port</code> CLI flag.</li>
       <li><strong>NODE_ENV</strong>: not directly used by webjs (it uses the <code>dev</code> flag from the CLI command), but your app code and dependencies may read it.</li>
     </ul>
     <p>For app-specific environment variables, use <code>process.env</code> in server-side code (pages, server actions, middleware, API routes). These are never exposed to the client.</p>
@@ -184,8 +184,8 @@ RUN npm ci --omit=dev
 # Copy app source as-is; the server serves it directly
 COPY . .
 
-EXPOSE 3000
-HEALTHCHECK CMD curl -f http://localhost:3000/__webjs/health || exit 1
+EXPOSE 8080
+HEALTHCHECK CMD curl -f http://localhost:8080/__webjs/health || exit 1
 
 CMD ["npx", "webjs", "start"]</pre>
     <p>Tips:</p>
@@ -202,7 +202,7 @@ CMD ["npx", "webjs", "start"]</pre>
 
     <h3>nginx</h3>
     <pre>upstream webjs {
-    server 127.0.0.1:3000;
+    server 127.0.0.1:8080;
 }
 
 server {
@@ -227,7 +227,7 @@ server {
 
     <h3>Caddy</h3>
     <pre>example.com {
-    reverse_proxy localhost:3000
+    reverse_proxy localhost:8080
 }</pre>
     <p>Caddy automatically provisions TLS certificates via Let's Encrypt and enables HTTP/2. It also handles WebSocket upgrades transparently.</p>
 
@@ -243,7 +243,7 @@ After=network.target
 Type=simple
 User=www
 WorkingDirectory=/srv/my-app
-ExecStart=/usr/bin/webjs start --port 3000
+ExecStart=/usr/bin/webjs start --port 8080
 Restart=on-failure
 RestartSec=5
 Environment=NODE_ENV=production

docs/app/docs/getting-started/page.ts

@@ -20,7 +20,7 @@ npm i -g @webjsdev/cli
 # scaffold a new app
 webjs create my-app
 cd my-app && npm run dev
-# → http://localhost:3000</pre>
+# → http://localhost:8080</pre>
 
     <p>Every scaffold ships with Prisma + SQLite wired up (<code>prisma/schema.prisma</code> with an example <code>User</code> model and <code>lib/prisma.server.ts</code> singleton). Run <code>npm run db:migrate</code> the first time to create <code>prisma/dev.db</code>.</p>
 
@@ -116,7 +116,7 @@ Counter.register('my-counter');</pre>
 
     <h3>Run it</h3>
     <pre>npm run dev
-# → http://localhost:3000</pre>
+# → http://localhost:8080</pre>
 
     <p>That's it. No build step, no bundler config, no compilation. Edit any <code>.ts</code> file, refresh, and see it.</p>
 

docs/app/docs/server-actions/page.ts

@@ -337,7 +337,7 @@ export class TodoApp extends WebComponent {
 TodoApp.register('todo-app');
 
 // 3. Call the REST endpoint from curl
-// curl -X POST http://localhost:3000/api/todos \\
+// curl -X POST http://localhost:8080/api/todos \\
 //   -H 'Content-Type: application/json' \\
 //   -d '{"text":"Buy milk"}'
 // => {"id":1,"text":"Buy milk","done":false,"createdAt":"2026-04-15T..."}</pre>

docs/app/docs/websockets/page.ts

@@ -128,7 +128,7 @@ conn.close();</pre>
     <h3>URL Resolution</h3>
     <p>Relative paths like <code>'/api/chat'</code> are automatically promoted to the correct WebSocket URL based on the current page's protocol:</p>
     <ul>
-      <li><code>http://</code> page: <code>ws://localhost:3000/api/chat</code></li>
+      <li><code>http://</code> page: <code>ws://localhost:8080/api/chat</code></li>
       <li><code>https://</code> page: <code>wss://example.com/api/chat</code></li>
     </ul>
     <p>Absolute <code>ws://</code> or <code>wss://</code> URLs pass through unchanged.</p>
@@ -498,7 +498,7 @@ export function WS(ws: WebSocket) {
 import type { WebSocket } from 'ws';
 
 export function WS(ws: WebSocket, req: Request, { params }: { params: { roomId: string } }) {
-  const room = params.roomId;  // e.g. "general" for ws://localhost:3000/api/rooms/general
+  const room = params.roomId;  // e.g. "general" for ws://localhost:8080/api/rooms/general
   joinRoom(room, ws);
   ws.on('message', (data) =&gt; broadcastToRoom(room, data.toString(), ws));
   ws.on('close', () =&gt; leaveRoom(room, ws));

examples/blog/CONVENTIONS.md

@@ -209,7 +209,7 @@ variables control infrastructure (no config files needed):
 | `AUTH_SECRET` | Required for auth JWT signing (32+ random chars) |
 | `AUTH_GOOGLE_ID` | Google OAuth client ID (optional) |
 | `AUTH_GITHUB_ID` | GitHub OAuth client ID (optional) |
-| `PORT` | Server port (default: 3000) |
+| `PORT` | Server port (default: 8080) |
 | `WEBJS_PUBLIC_*` | Any env var starting with this prefix is exposed to the browser as `process.env.WEBJS_PUBLIC_X`. Components can read it directly. No build step, no transform. Use for API base URLs, Stripe publishable keys, analytics IDs, anything that is intended to be visible client-side. |
 
 **Server-only by default.** Any env var without the `WEBJS_PUBLIC_` prefix never reaches the browser. Reading `process.env.DATABASE_URL` from a component returns `undefined`, the same as a typo. The prefix is fail-closed: secrets cannot accidentally leak.

packages/cli/README.md

@@ -18,7 +18,7 @@ Then scaffold a new app anywhere:
 ```sh
 webjs create my-app
 cd my-app && npm run dev
-# → http://localhost:3000
+# → http://localhost:8080
 ```
 
 One-shot without a global install, two ways: