@nativescript/vite 8.0.0-beta.0 → 8.0.0-dev.0

package/README.md

@@ -44,24 +44,17 @@ npx nativescript-vite init
 
 This will:
 
-- Generate a `vite.config.ts` using the detected project flavor (Angular, Vue, React, Solid, TypeScript, or JavaScript) and the corresponding helper subpath from `@nativescript/vite`.
-- Add (or update) the following npm scripts in your app `package.json`:
-	- `dev:ios`
-	- `dev:android`
-	- `dev:server:ios`
-	- `dev:server:android`
-	- `ios`
-	- `android`
-- Add the devDependencies `concurrently` and `wait-on`.
+- Generate a `vite.config.mts` using the detected project flavor (Angular, Vue, React, Solid, TypeScript, or JavaScript — or a flavor a dependency declares, see below) and the corresponding helper subpath from `@nativescript/vite`.
 - Add the dependency `@valor/nativescript-websockets`.
 - Append `.ns-vite-build` to `.gitignore` if it is not already present.
 
-After running `init`, you now have two ways to work with Vite:
+After running `init`, you have two ways to work with Vite:
 
-1. HMR workflow
+1. HMR workflow (default — the CLI starts the dev server for you)
 
 ```bash
-npm run dev:ios
+ns debug ios
+ns debug android
 ```
 
 2. Standard dev workflow (non-HMR)
@@ -71,9 +64,75 @@ ns debug ios --no-hmr
 ns debug android --no-hmr
 ```
 
+### Android: automatic `adb reverse`
+
+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
+
+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` | 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>` |
+
+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
+
+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
+NS_HMR_PORT=5173 NS_VITE_DIST_DIR=.ns-vite-build/ios ns debug ios
+
+# Terminal 2: Android
+NS_HMR_PORT=5174 NS_VITE_DIST_DIR=.ns-vite-build/android ns debug android
+```
+
+The inline environment syntax above is for POSIX shells; use the equivalent
+assignment on Windows.
+
+### Advanced: running `vite serve` yourself
+
+The dev server is just `vite serve -- --env.<platform> --env.hmr`. You can run
+it standalone for diagnostics, but do **not** run it alongside `ns run`/`ns debug`
+for the same platform — both would try to bind the same port. CLI-managed is the
+supported default.
+
 ## Usage
 
-1) Create `vite.config.ts`:
+1) Create `vite.config.mts` (the `.mts` extension keeps the config ESM without setting `"type": "module"` in the app's package.json, avoiding Vite's `configLoader: 'native'` warning):
 
 ```ts
 import { defineConfig, mergeConfig, UserConfig } from 'vite';
@@ -93,6 +152,22 @@ import { solidConfig } from '@nativescript/vite/solid';
 import { vueConfig } from '@nativescript/vite/vue';
 ```
 
+### Flavors from other packages
+
+A framework can ship its own flavor — config helper, server strategy and device-side
+client strategy — as a package, using `@nativescript/vite/framework` and
+`@nativescript/vite/hmr/client/framework.js`. `init` and flavor detection pick it up from a
+`nativescript.vite` declaration in that package's `package.json`. The Octane flavor,
+[`@nativescript-community/vite-octane`](https://github.com/nativescript-community/octane), is built this way:
+
+```ts
+import { octaneConfig } from '@nativescript-community/vite-octane';
+
+export default defineConfig(({ mode }) => octaneConfig({ mode }));
+```
+
+See [docs/framework-flavors.md](./docs/framework-flavors.md) for the full walkthrough.
+
 2) Update `nativescript.config.ts`:
 
 ```ts
@@ -101,7 +176,7 @@ import { NativeScriptConfig } from '@nativescript/core';
 export default {
 	// add these:
 	bundler: 'vite',
-	bundlerConfigPath: 'vite.config.ts',
+	bundlerConfigPath: 'vite.config.mts',
 } as NativeScriptConfig;
 ```
 

package/bin/cli.cjs

@@ -2,25 +2,19 @@
 
 // Small CommonJS launcher that forwards to the ESM library's init helper.
 // This allows `npx @nativescript/vite init` to work reliably across npm versions.
+// The package is ESM-only (no dist/index.cjs); the init entry lives at
+// `../helpers/init.js` relative to this file in both the source tree and the
+// published `dist/packages/vite` layout.
 
 (async () => {
   try {
-    const mod = await import('../dist/index.cjs').catch(async () => import('../index.js'));
     if (process.argv[2] === 'init') {
-      if (typeof mod.runInit === 'function') {
-        await mod.runInit();
-      } else if (mod && mod.helpers && typeof mod.helpers.runInit === 'function') {
-        await mod.helpers.runInit();
-      } else if (mod && mod.default && typeof mod.default.runInit === 'function') {
-        await mod.default.runInit();
+      const { runInit } = await import('../helpers/init.js');
+      if (typeof runInit === 'function') {
+        await runInit();
       } else {
-        const initMod = await import('../helpers/init.js');
-        if (typeof initMod.runInit === 'function') {
-          await initMod.runInit();
-        } else {
-          console.error('[@nativescript/vite] `runInit` not found in helpers.');
-          process.exitCode = 1;
-        }
+        console.error('[@nativescript/vite] `runInit` not found in helpers/init.js.');
+        process.exitCode = 1;
       }
     } else {
       console.log('Usage: npx @nativescript/vite init');

package/configuration/angular.d.ts

@@ -1,4 +1,37 @@
 import { type UserConfig } from 'vite';
-export declare const angularConfig: ({ mode }: {
-    mode: any;
+/**
+ * File replacement entry forwarded to `@analogjs/vite-plugin-angular`.
+ * `replace` and `with` may be absolute paths or paths relative to
+ * `workspaceRoot` (when supplied). The Analog plugin matches against the
+ * resolved id with `endsWith(replace)`, so absolute paths Just Work in Nx
+ * / pnpm / Rush layouts where the source tree may live above the project
+ * root.
+ */
+export interface AngularFileReplacement {
+    replace: string;
+    with: string;
+    ssr?: string;
+}
+export declare const angularConfig: ({ mode, fileReplacements, workspaceRoot, }: {
+    mode: string;
+    /**
+     * Angular CLI–style file replacements (e.g. `environment.ts` →
+     * `environment.stg.ts`) forwarded to `@analogjs/vite-plugin-angular`'s
+     * `replaceFiles` plugin AND to the Angular TypeScript CompilerHost.
+     *
+     * Required for monorepo apps that need configuration-specific
+     * environment files: the Angular host reads source files via its own
+     * file-system layer, so a Vite `resolveId`/`load` plugin alone cannot
+     * swap a `.ts` file for `vite serve` / HMR — the host will still
+     * compile the original source from disk. Passing the list here ensures
+     * the host sees the replacement before TypeScript ever parses the
+     * file, matching how Angular CLI's `fileReplacements` works.
+     */
+    fileReplacements?: AngularFileReplacement[];
+    /**
+     * Workspace root used by `@analogjs/vite-plugin-angular` to resolve
+     * relative `fileReplacements` paths. Absolute paths bypass this.
+     * Defaults to `process.cwd()`.
+     */
+    workspaceRoot?: string;
 }) => UserConfig;