monorepo-template / backend

---
description: "Local dev port allocation - role ranges, registry, inspector_port, strictPort, multi-config wrangler."
alwaysApply: false
globs: **/wrangler.jsonc,apps/*/package.json,apps/front-*/vite.config.ts
---

# Local Dev Ports

Follow the ranges and registry below when scaffolding or editing port config.

## Role ranges

| Role | Prefix | Local HTTP ports |
|------|--------|------------------|
| HTTP gateway | `worker-api` | **8700–8709** |
| Business worker (RPC) | `worker-*` | **8710–8739** |
| Queue-only consumer | `queue-*` | **8740–8759** |
| Webhook ingress | `webhook-*` | **8760–8779** |
| MCP server | `mcp-*` | **8780–8789** |
| Growth reserve | - | **8790–8799** |
| Frontend (Vite) | `front-*` | **5170–5199** (dev), **4170–4199** (preview) |

## Assigned registry

| App | Role | Dev | Preview |
|-----|------|-----|---------|
| `worker-api` | gateway | **8700** | - |
| `front-app` | frontend | **5174** | **4174** |

## Local-dev rules

- Assign the **next free port** in the role’s range; record it in `package.json` → `monorepo.devPort` and `wrangler.jsonc` `dev.port` (or Vite `server.port` / `preview.port`).
- **RPC / queue** workers still set a stable `dev.port` for standalone `wrangler dev`, but production has no public URL. Prefer multi-config: `wrangler dev -c apps/worker-api/wrangler.jsonc -c apps/worker-foo/wrangler.jsonc` (first config = HTTP primary). See also [workers-config.mdc](workers-config.mdc).
- **MCP servers** are public HTTP locally and in prod; keep handlers thin and call `worker-*` over RPC. Never expose credential rotation or other irreversible privileged actions on the MCP surface (see [guardrails.mdc](../core/guardrails.mdc)).
- **Inspectors:** always `inspector_port: 0` (ephemeral).
- **Frontends:** `strictPort: true` on both `server` and `preview` (see [vite-config.mdc](../frontend/vite-config.mdc)).