Guide: Next.js (No Docker)

Use Case

You have one Next.js repo and run npm run dev directly. You want multiple Muxy workspaces active at once, each with isolated ports and browser tabs.

Project Settings Explained

Port Definitions

FRONTEND_PORT

Reserve a named port per workspace. This avoids collisions when two branches both run a dev server.

Setup Script

npm i
cp /shared/.env .env

npm i ensures dependencies are present in new workspaces.cp creates an independent .env copy per workspace. Copy is safer when you want branch-local env edits. A symlink keeps one source of truth, but changes affect all workspaces and can cause surprising cross-branch coupling.

Processes

PORT=$FRONTEND_PORT npm run dev

This binds Next.js to the workspace-reserved host port, so browser sessions and checks target the correct workspace instance.

Browser Sessions

http://localhost:$FRONTEND_PORT

Browser session URLs should use named ports so each workspace opens its own app tab reliably.

Status Checks

curl -fsS http://localhost:$FRONTEND_PORT

Status checks give early signal when the server is down, hung, or failed after startup. Useful for restart policies and for quickly seeing run health in the Muxy UI.

Other Status Check Use Cases

• • Detect API readiness with health endpoints before opening dependent frontend pages.
• • Alert when background workers die but terminal windows remain open.
• • Detect auth/certificate errors by running a command that validates expected response content.