Skip to content

feat(vite): allow auto port availability selection #11351

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
NathanWalker wants to merge 1 commit into
base: main
Choose a base branch
from
+37 −15
Open

feat(vite): allow auto port availability selection #11351

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 33 additions & 14 deletions packages/vite/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,31 +66,51 @@ ns debug android --no-hmr

### Android: automatic `adb reverse`

For Android HMR the CLI automatically runs `adb reverse tcp:5173 tcp:5173`
(using the SDK-resolved adb, scoped to the deploy target, after the device is
ready) so the device reaches the dev server through the ADB tunnel at
`127.0.0.1:5173`. Relevant opt-outs:
For Android HMR the CLI automatically runs `adb reverse tcp:<port> tcp:<port>`
for the session's dev-server port (using the SDK-resolved adb, scoped to the
deploy target, after the device is ready) so the device reaches the dev server
through the ADB tunnel at `127.0.0.1:<port>`. Relevant opt-outs:

- `NS_HMR_NO_ADB_REVERSE=1` — skip the tunnel and use `10.0.2.2`.
- `NS_HMR_PREFER_LAN_HOST=1` — physical device over Wi-Fi; emit the host's LAN IP.
- `NS_HMR_HOST=<host[:port]>` — point the device at an explicit origin (CI / tunnels).

## Custom HMR sessions

A NativeScript Vite HMR session may use custom server and staging settings:
The CLI picks the dev-server settings for each session on its own:

- **Port** — the first free port at or above `NS_HMR_PORT` (default `5173`),
the same way `vite` moves off a busy port. Whatever it picks is baked into
the device URLs, bound by the dev server and (on Android) tunnelled with
`adb reverse`, so all three always agree.
- **Staging directory** — `.ns-vite-build/<platform>`, so iOS and Android
builds never overwrite each other's output.

Both can still be pinned explicitly:

| Environment variable | Purpose | Default |
| --- | --- | --- |
| `NS_HMR_PORT` | Vite server port used by the generated device HTTP and websocket URLs (the CLI reverses and probes this port) | `5173` |
| `NS_VITE_DIST_DIR` | Project-relative staging directory used for Vite output before the NativeScript CLI copies it into the platform app | `.ns-vite-build` |
| `NS_HMR_PORT` | Preferred Vite dev-server port; the CLI moves to the next free port when it is taken | `5173` |
| `NS_HMR_STRICT_PORT` | Fail instead of moving when `NS_HMR_PORT` is taken (Vite's `strictPort`) — for tunnels / CI that forward a fixed port | unset |
| `NS_VITE_DIST_DIR` | Project-relative staging directory used for Vite output before the NativeScript CLI copies it into the platform app | `.ns-vite-build/<platform>` |

Leave both unset for the standard single-session workflow.
The environment settings only need to be visible to the `ns` process — the CLI
propagates them (and the values it picks) to the dev server it spawns.

### Running two platforms at once

The CLI runs **one dev server per port**. To run iOS and Android HMR
simultaneously for the same app, give each its own port and staging dir so the
servers and their platform-specific bundles don't collide:
Start both; nothing to configure:

```bash
# Terminal 1
ns debug ios # dev server on 5173

# Terminal 2
ns debug android # 5173 is busy → dev server on 5174
```

Each session gets its own port and staging directory. Older CLIs that don't
pick ports need them set by hand per terminal:

```bash
# Terminal 1: iOS
Expand All @@ -100,9 +120,8 @@ NS_HMR_PORT=5173 NS_VITE_DIST_DIR=.ns-vite-build/ios ns debug ios
NS_HMR_PORT=5174 NS_VITE_DIST_DIR=.ns-vite-build/android ns debug android
```

The environment settings only need to be visible to the `ns` process — the CLI
propagates them to the dev server it spawns. The inline environment syntax
above is for POSIX shells; use the equivalent assignment on Windows.
The inline environment syntax above is for POSIX shells; use the equivalent
assignment on Windows.

### Advanced: running `vite serve` yourself

Expand Down
5 changes: 4 additions & 1 deletion packages/vite/configuration/base.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -455,7 +455,10 @@ export const baseConfig = ({ mode, flavor }: { mode: string; flavor?: string }):
// host devices are told to use is decided separately by
// `resolveDeviceReachableHost`. `NS_HMR_HOST` overrides.
host: process.env.NS_HMR_HOST || '0.0.0.0',
// Use the configured stable port so multiple platform sessions can coexist.
// The CLI picks a free port per platform session and hands
// it in as `NS_HMR_PORT`; that same port is baked into
// `bundle.mjs` and tunnelled with `adb reverse`, so Vite
// must not silently move off it — bind it or fail loudly.
port: hmrPort,
strictPort: true,
https: useHttps
Expand Down
Loading