# Framework scaffolders, dev-server commands, and port overrides

Five frameworks supported. Each row gives the exact command set the prototype-host skill runs in phases 2 and 5.

## Selection defaults

| Surface intent | Default framework | Reason |
|---|---|---|
| `landing` | `static` | One HTML file rendered from `01-narrative/LANDING.md` is faster to ship and faster to load than a Vite bundle. Lighthouse-clean by construction. |
| `prototype` | `vite` | Vue/React/Svelte all supported; HMR is the founder's iteration loop. |

If the operator names a framework explicitly, use that. Otherwise these defaults stand.

## `static`

No scaffolder. The skill writes a single `index.html` directly into `<surface-dir>/` from `01-narrative/LANDING.md`, with brand tokens inlined into `<style>` in the `<head>`.

- **Build:** none (raw HTML); for a `dist/` build (if the operator adds Tailwind etc later) the skill respects `<surface-dir>/dist/` if present.
- **Serve:** `cloudflared file-server --port <port> <surface-dir>` (or `<surface-dir>/dist` if a build directory exists).
- **Port override:** `--port <port>` on `cloudflared file-server`.

## `vite`

- **Scaffold:** `cd <surface-dir-parent> && npm create vite@latest <surface-name> -- --template vanilla-ts -- --yes`. The agent prompts the operator before this if they want a non-vanilla template (`react-ts`, `svelte-ts`, `vue-ts`); otherwise `vanilla-ts` is the default — the founder can rewrite `index.html` + `src/main.ts` to anything from there.
- **Install:** `cd <surface-dir> && npm install`
- **Build:** `npm run build` (outputs to `<surface-dir>/dist/`)
- **Dev server:** `npm run dev -- --port <port> --host 127.0.0.1`
- **Port override:** `--port <port>` (Vite respects the flag; `PORT=` is ignored).

## `next`

- **Scaffold:** `cd <surface-dir-parent> && npx -y create-next-app@latest <surface-name> --typescript --app --tailwind --eslint --src-dir --import-alias "@/*" --use-npm --yes`
- **Install:** scaffolder runs `npm install` automatically.
- **Build:** `npm run build`
- **Dev server:** `npm run dev -- -p <port> -H 127.0.0.1`
- **Port override:** `-p <port>` (Next.js dev/start respect the flag; `PORT=` also works but `-p` is explicit).

## `sveltekit`

- **Scaffold:** `cd <surface-dir-parent> && npx -y sv create <surface-name> --template minimal --types ts --no-add-ons --install npm`
- **Install:** scaffolder runs `npm install` automatically when `--install npm` is passed.
- **Build:** `npm run build`
- **Dev server:** `npm run dev -- --port <port> --host 127.0.0.1`
- **Port override:** `--port <port>`.

## `astro`

- **Scaffold:** `cd <surface-dir-parent> && npm create astro@latest <surface-name> -- --template minimal --typescript strict --install --no-git --yes`
- **Install:** scaffolder runs `npm install` when `--install` is passed.
- **Build:** `npm run build` (outputs to `<surface-dir>/dist/`)
- **Dev server:** `npm run dev -- --port <port> --host 127.0.0.1`
- **Port override:** `--port <port>`.

## Why `--host 127.0.0.1`

Every dev server above binds to `127.0.0.1`, not `0.0.0.0`. Cloudflared connects to the loopback address; binding to `0.0.0.0` would expose the dev server on the install device's LAN address, which is unwanted (LAN clients should reach the prototype through the tunnel, not directly).

## Why no `--yes` on `create-next-app` interactive prompts in older versions

`create-next-app@latest` (≥14.2) treats all listed flags as the answer set and runs non-interactively. If a flag is omitted it falls back to a TTY prompt — fatal under the agent's non-TTY Bash invocation. Always pass every flag the table lists.
