@nativescript/vite 8.0.0-alpha.2 → 8.0.0-alpha.20

package/configuration/angular.d.ts

@@ -1,4 +1,37 @@
 import { type UserConfig } from 'vite';
-export declare const angularConfig: ({ mode }: {
+/**
+ * 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;

package/configuration/angular.js

@@ -7,11 +7,14 @@ import { angularLinkerVitePlugin, angularLinkerVitePluginPost } from '../helpers
 import { synthesizeMissingInjectableFactories } from '../helpers/angular/synthesize-injectable-factories.js';
 import { ensureSharedAngularLinker, resolveAngularFileSystem } from '../helpers/angular/shared-linker.js';
 import { inlineDecoratorComponentTemplates } from '../helpers/angular/inline-decorator-component-templates.js';
+import { appendComponentHmrRegistration, findComponentClassNames, INJECTION_MARKER as HMR_REGISTER_MARKER } from '../helpers/angular/inject-component-hmr-registration.js';
+import { injectAngularHmrViteIgnore } from '../helpers/angular/inject-hmr-vite-ignore.js';
 import { synthesizeDecoratorCtorParameters } from '../helpers/angular/synthesize-decorator-ctor-parameters.js';
-import { containsRealNgDeclare } from '../helpers/angular/util.js';
+import { containsRealNgDeclare, stripJsComments } from '../helpers/angular/util.js';
 import { baseConfig } from './base.js';
 import { getCliFlags } from '../helpers/cli-flags.js';
 import { resolveRelativeToImportMeta } from '../helpers/import-meta-path.js';
+import { resolveVerboseFlag } from '../helpers/logging.js';
 // Lazily import the Angular linker factory function. Used by chunk-level linkers
 // to create FRESH plugin instances per invocation (avoiding stale state in watch mode).
 let _cachedLinkerFactory = null;
@@ -87,10 +90,7 @@ function angularRollupLinker(projectRoot) {
                     return null;
                 const plugin = createLinker({ sourceMapping: false, fileSystem: angularFileSystem });
                 if (debug) {
-                    try {
-                        console.log('[ns-angular-linker][rollup-load] linking', cleanId);
-                    }
-                    catch { }
+                    console.log('[ns-angular-linker][rollup-load] linking', cleanId);
                 }
                 const result = await babel.transformAsync(code, {
                     filename: cleanId,
@@ -123,10 +123,7 @@ function angularRollupLinker(projectRoot) {
             try {
                 const plugin = createLinker({ sourceMapping: false, fileSystem: angularFileSystem });
                 if (debug) {
-                    try {
-                        console.log('[ns-angular-linker][rollup] linking', cleanId);
-                    }
-                    catch { }
+                    console.log('[ns-angular-linker][rollup] linking', cleanId);
                 }
                 const result = await babel.transformAsync(code, {
                     filename: cleanId,
@@ -148,6 +145,37 @@ function angularRollupLinker(projectRoot) {
 const cliFlags = getCliFlags();
 const isDevEnv = process.env.NODE_ENV !== 'production';
 const hmrActive = isDevEnv && !!cliFlags.hmr;
+/**
+ * Web-style template HMR opt-out.
+ *
+ * When `hmrActive` is true we default to the in-place template-replacement
+ * pipeline (`liveReload: true` on Analog → `_enableHmr: true` on the Angular
+ * TS compiler → `angular:component-update` events served via the
+ * `/@ng/component` middleware → `ɵɵreplaceMetadata` on the live class).
+ * Setting `_enableHmr: true` also forces Analog to set
+ * `externalRuntimeStyles: true`, changing how component styles are emitted
+ * (URLs fetched lazily instead of inlined). On the web that's fine; for
+ * NativeScript it's a new code path that touches the SCSS / Tailwind
+ * pipeline and the iOS runtime's HTTP module loader.
+ *
+ * If a project hits a regression on day one (broken styling, unresolved
+ * `?ngcomp=` imports, etc.) the user can roll back to the legacy reboot
+ * pipeline without an upstream patch by setting the env flag. We honour
+ * `0`, `false`, `off`, and `no` (case-insensitive) as "off" — anything
+ * else (including unset) keeps the new path on.
+ *
+ * The flag is read once at module load, mirroring how `hmrActive` is
+ * computed, so a project can flip it via `cross-env` in their dev script
+ * and never look back.
+ */
+const angularLiveReloadDisabledByEnv = (() => {
+    const raw = process.env.NS_VITE_ANGULAR_LIVE_RELOAD;
+    if (typeof raw !== 'string')
+        return false;
+    const v = raw.trim().toLowerCase();
+    return v === '0' || v === 'false' || v === 'off' || v === 'no';
+})();
+const hmrAngularLiveReload = hmrActive && !angularLiveReloadDisabledByEnv;
 const projectRoot = process.cwd();
 const tsConfigAppPath = path.resolve(projectRoot, 'tsconfig.app.json');
 const tsConfigPath = path.resolve(projectRoot, 'tsconfig.json');
@@ -156,21 +184,61 @@ if (!fs.existsSync(tsConfigAppPath) && fs.existsSync(tsConfigPath)) {
     tsConfig = tsConfigPath;
 }
 function normalizeAngularWatchPath(filePath) {
-    return filePath.split('?', 1)[0].replace(/\\/g, '/');
+    return filePath
+        .split('?', 1)[0]
+        .replace(/\\/g, '/')
+        .replace(/^file:\/\//, '');
+}
+function normalizeAngularWatchKey(filePath) {
+    const normalizedPath = normalizeAngularWatchPath(filePath);
+    const fileSystemPath = normalizedPath.startsWith('/@fs/') ? normalizedPath.slice('/@fs'.length) : normalizedPath;
+    const normalizedProjectRoot = projectRoot.replace(/\\/g, '/').replace(/\/$/, '');
+    if (normalizedProjectRoot && fileSystemPath.startsWith(normalizedProjectRoot)) {
+        const relative = fileSystemPath.slice(normalizedProjectRoot.length);
+        return relative.startsWith('/') ? relative : `/${relative}`;
+    }
+    return fileSystemPath;
+}
+function getAngularWatchKeys(filePath) {
+    const normalizedPath = normalizeAngularWatchPath(filePath);
+    const keys = new Set();
+    keys.add(normalizedPath);
+    keys.add(normalizeAngularWatchKey(normalizedPath));
+    return Array.from(keys).filter(Boolean);
+}
+function resolveAngularWatchFilePath(filePath) {
+    const normalizedPath = normalizeAngularWatchPath(filePath);
+    const fileSystemPath = normalizedPath.startsWith('/@fs/') ? normalizedPath.slice('/@fs'.length) : normalizedPath;
+    if (path.isAbsolute(fileSystemPath) && fs.existsSync(fileSystemPath)) {
+        return fileSystemPath;
+    }
+    if (fileSystemPath.startsWith('/')) {
+        return path.resolve(projectRoot, `.${fileSystemPath}`);
+    }
+    return path.resolve(projectRoot, fileSystemPath);
 }
 function extractComponentAssetPaths(code, componentId) {
     const componentPath = normalizeAngularWatchPath(componentId);
     const assetPaths = new Set();
     const resolveAssetPath = (assetPath) => normalizeAngularWatchPath(path.resolve(path.dirname(componentPath), assetPath));
-    const templateUrlMatch = code.match(/templateUrl\s*:\s*['"](.+?\.(?:html|htm))['"]/);
+    // Blank out `//` and `/* */` comments before scanning. The regexes below
+    // are intentionally simple (no JS parser) so they would otherwise match
+    // commented-out `templateUrl` / `styleUrls` declarations and register
+    // phantom asset deps via `addWatchFile`. In current Rolldown-Vite that
+    // also enrolls them as `_addedImports`, which `vite:import-analysis`
+    // then tries to resolve — surfacing as a misleading
+    // `Failed to resolve import "<file>" from "<importer>". Does the file
+    // exist?` pre-transform error if the file (predictably) doesn't exist.
+    const scanCode = stripJsComments(code);
+    const templateUrlMatch = scanCode.match(/templateUrl\s*:\s*['"](.+?\.(?:html|htm))['"]/);
     if (templateUrlMatch) {
         assetPaths.add(resolveAssetPath(templateUrlMatch[1]));
     }
-    const styleUrlMatch = code.match(/styleUrl\s*:\s*['"](.+?\.(?:css|less|sass|scss))['"]/);
+    const styleUrlMatch = scanCode.match(/styleUrl\s*:\s*['"](.+?\.(?:css|less|sass|scss))['"]/);
     if (styleUrlMatch) {
         assetPaths.add(resolveAssetPath(styleUrlMatch[1]));
     }
-    const styleUrlsMatch = code.match(/styleUrls\s*:\s*\[([\s\S]*?)\]/m);
+    const styleUrlsMatch = scanCode.match(/styleUrls\s*:\s*\[([\s\S]*?)\]/m);
     if (styleUrlsMatch) {
         for (const match of styleUrlsMatch[1].matchAll(/['"](.+?\.(?:css|less|sass|scss))['"]/g)) {
             assetPaths.add(resolveAssetPath(match[1]));
@@ -179,9 +247,18 @@ function extractComponentAssetPaths(code, componentId) {
     return Array.from(assetPaths);
 }
 function createAngularPlugins(opts) {
+    const verbose = resolveVerboseFlag();
     const assetToComponents = new Map();
     const componentToAssets = new Map();
     const pendingComponentInvalidations = new Set();
+    // Shared state between the `enforce: 'pre'` discovery plugin and the
+    // `enforce: 'post'` injection plugin. Maps a clean (no-querystring)
+    // .ts file id to the list of `@Component`-decorated class names found
+    // in its RAW TypeScript source. The pre plugin populates this map;
+    // the post plugin reads it to know which class names to register
+    // against the compiled output. Cleared on each pre-plugin invocation
+    // so renames or `@Component` removals don't leave stale entries.
+    const componentsByCleanId = new Map();
     const untrackComponentAssets = (componentPath) => {
         const previousAssets = componentToAssets.get(componentPath);
         if (!previousAssets)
@@ -201,7 +278,7 @@ function createAngularPlugins(opts) {
         untrackComponentAssets(componentPath);
         if (assetPaths.length === 0)
             return;
-        const normalizedAssets = new Set(assetPaths.map((assetPath) => normalizeAngularWatchPath(assetPath)));
+        const normalizedAssets = new Set(assetPaths.flatMap((assetPath) => getAngularWatchKeys(assetPath)));
         componentToAssets.set(componentPath, normalizedAssets);
         for (const assetPath of normalizedAssets) {
             const components = assetToComponents.get(assetPath) || new Set();
@@ -209,43 +286,190 @@ function createAngularPlugins(opts) {
             assetToComponents.set(assetPath, components);
         }
     };
+    const isCandidateComponentTs = (cleanId) => {
+        if (!cleanId.endsWith('.ts'))
+            return false;
+        if (cleanId.includes('/node_modules/'))
+            return false;
+        if (cleanId.endsWith('.d.ts'))
+            return false;
+        if (cleanId.endsWith('.spec.ts') || cleanId.endsWith('.test.ts'))
+            return false;
+        return true;
+    };
     return [
+        // HMR self-registration runs in two phases:
+        //
+        //   1. (this plugin, `enforce: 'pre'`) Walk the raw TypeScript
+        //      source for each user `.ts` file and record the names of
+        //      any `@Component`-decorated classes into the shared
+        //      `componentsByCleanId` map. Discovery has to happen on the
+        //      raw source because the Analog Angular plugin rewrites
+        //      `@Component(...)` into static metadata calls and removes
+        //      the textual decorator pattern.
+        //
+        //   2. (`ns-component-hmr-register-post`, `enforce: 'post'`)
+        //      After the Analog Angular plugin has compiled the file,
+        //      append the global `__NS_HMR_REGISTER_COMPONENT__`
+        //      registration calls keyed by the names recorded in step 1.
+        //
+        // Why the two-phase split: the Analog Angular plugin's `transform`
+        // returns its OWN regenerated compiled output (from its internal
+        // `outputFiles` cache populated at `buildStart`), discarding any
+        // code modifications applied earlier in the pipeline. We
+        // previously appended the registration snippet here, in the pre
+        // plugin, and the snippet was silently dropped — leaving the
+        // HMR class registry empty and `getFreshComponentClass` returning
+        // `found=false reason=no-registry` after every reboot.
+        //
+        // Placement notes that still apply:
+        //   - `apply: 'serve'`: the registry runtime hook is dev-only;
+        //     production builds never need self-registration.
+        //   - Intentionally NOT gated on `hmrActive`. The injected
+        //     snippet self-guards with
+        //     `typeof globalThis.__NS_HMR_REGISTER_COMPONENT__ === 'function'`,
+        //     so it's a no-op when the runtime hook isn't installed
+        //     (e.g. `--no-hmr` users still serving modules through
+        //     Vite). Gating the transform itself on `hmrActive` produced
+        //     a silent failure mode where `--no-hmr` users got HMR
+        //     machinery up but never got the registration calls
+        //     injected, leaving the registry empty.
+        {
+            name: 'ns-component-hmr-register',
+            enforce: 'pre',
+            apply: 'serve',
+            transform(code, id) {
+                const cleanId = id.split('?', 1)[0];
+                if (!isCandidateComponentTs(cleanId))
+                    return null;
+                const componentNames = findComponentClassNames(code);
+                if (componentNames.length === 0) {
+                    // Drop any stale entry from a previous transform
+                    // pass; the file may have lost its `@Component`
+                    // decorator across a rename/refactor.
+                    componentsByCleanId.delete(cleanId);
+                    return null;
+                }
+                componentsByCleanId.set(cleanId, componentNames);
+                if (verbose) {
+                    console.info(`[ns-hmr][ns-component-hmr-register] discovered ${componentNames.length} component(s) in ${cleanId} (${componentNames.join(', ')})`);
+                }
+                // Discovery only — never modify the raw TS source. Any
+                // modification here is discarded by the Analog Angular
+                // plugin downstream; the actual snippet append happens
+                // in `ns-component-hmr-register-post`.
+                return null;
+            },
+        },
+        // Phase 2: append the HMR registration snippet to the compiled
+        // JS output produced by `@analogjs/vite-plugin-angular`. Runs
+        // `enforce: 'post'` so we see the post-Angular code (where the
+        // pre plugin's work would otherwise be discarded). Reads the
+        // component names recorded by the pre plugin via
+        // `componentsByCleanId`.
+        {
+            name: 'ns-component-hmr-register-post',
+            enforce: 'post',
+            apply: 'serve',
+            transform(code, id) {
+                const cleanId = id.split('?', 1)[0];
+                if (!isCandidateComponentTs(cleanId))
+                    return null;
+                const componentNames = componentsByCleanId.get(cleanId);
+                if (!componentNames || componentNames.length === 0)
+                    return null;
+                // Idempotency: the Vite cache may replay the transform
+                // pipeline on cached modules. The marker comment is
+                // inserted by `appendComponentHmrRegistration` and
+                // guards against double-injection. We also defensively
+                // short-circuit here so we don't have to allocate the
+                // suffix string on every cached re-run.
+                if (code.includes(HMR_REGISTER_MARKER))
+                    return null;
+                const result = appendComponentHmrRegistration(code, componentNames);
+                if (!result.code)
+                    return null;
+                if (verbose) {
+                    console.info(`[ns-hmr][ns-component-hmr-register-post] appended registrations for ${result.componentNames.length} component(s) in ${cleanId} (${result.componentNames.join(', ')})`);
+                }
+                // Returning `null` for the source map is acceptable for
+                // dev: lines 1..N (the original compiled body) keep
+                // the upstream Angular source map; the appended snippet
+                // is invisible to debuggers but harmless. For
+                // production-grade source maps a MagicString-based
+                // pass-through could be used; not required for HMR.
+                return { code: result.code, map: null };
+            },
+        },
         // Allow external html template changes to trigger hot reload: Make .ts files depend on their .html templates
         {
             name: 'angular-template-deps',
             enforce: 'pre',
             transform(code, id) {
                 const componentPath = normalizeAngularWatchPath(id);
-                if (!componentPath.endsWith('.ts'))
+                const componentKey = normalizeAngularWatchKey(id);
+                if (!componentKey.endsWith('.ts'))
                     return null;
                 const assetPaths = extractComponentAssetPaths(code, componentPath);
-                trackComponentAssets(componentPath, assetPaths);
+                trackComponentAssets(componentKey, assetPaths);
                 for (const assetPath of assetPaths) {
                     this.addWatchFile(assetPath);
                 }
+                // Diagnostic: surface which .ts files we've registered
+                // asset (template/styleUrls) dependencies for. This is
+                // the first fence the HTML→TS invalidation pipeline must
+                // pass — if we never see a [tracking] log for the
+                // component we're editing, the watcher will never fire
+                // and `pendingComponentInvalidations` stays empty.
+                if (verbose) {
+                    console.info(`[ns-hmr][angular-template-deps] [tracking] componentKey=${componentKey} assets=${assetPaths.length} (${assetPaths.slice(0, 4).join(', ')})`);
+                }
                 return null;
             },
             watchChange(id) {
                 const changedPath = normalizeAngularWatchPath(id);
-                const components = assetToComponents.get(changedPath);
+                const components = new Set();
+                for (const assetKey of getAngularWatchKeys(changedPath)) {
+                    for (const componentPath of assetToComponents.get(assetKey) || []) {
+                        components.add(componentPath);
+                    }
+                }
                 if (components?.size) {
                     for (const componentPath of components) {
                         pendingComponentInvalidations.add(componentPath);
                     }
+                    if (verbose) {
+                        console.info(`[ns-hmr][angular-template-deps] watchChange [via assetToComponents] changed=${changedPath} → invalidating ${components.size} component(s):`, Array.from(components));
+                    }
                     return;
                 }
                 if (/\.(html|htm)$/i.test(changedPath)) {
                     const componentPath = changedPath.replace(/\.(html|htm)$/i, '.ts');
-                    if (fs.existsSync(componentPath)) {
-                        pendingComponentInvalidations.add(componentPath);
+                    const exists = fs.existsSync(resolveAngularWatchFilePath(componentPath));
+                    if (exists) {
+                        const componentKey = normalizeAngularWatchKey(componentPath);
+                        pendingComponentInvalidations.add(componentKey);
+                        if (verbose) {
+                            console.info(`[ns-hmr][angular-template-deps] watchChange [via fallback .html→.ts] changed=${changedPath} componentKey=${componentKey}`);
+                        }
+                    }
+                    else {
+                        // Truly anomalous: a watched template/style asset has no companion
+                        // `.ts` file, so we cannot route the edit through the Angular
+                        // HMR pipeline. Always-on warning so it surfaces in non-verbose
+                        // runs — silent fallback would hide a real wiring break.
+                        console.warn(`[ns-hmr][angular-template-deps] watchChange [no companion .ts found] changed=${changedPath} expectedTs=${componentPath}`);
                     }
                 }
             },
             shouldTransformCachedModule({ id }) {
-                const componentPath = normalizeAngularWatchPath(id);
+                const componentPath = normalizeAngularWatchKey(id);
                 if (!pendingComponentInvalidations.has(componentPath))
                     return null;
                 pendingComponentInvalidations.delete(componentPath);
+                if (verbose) {
+                    console.info(`[ns-hmr][angular-template-deps] shouldTransformCachedModule → re-transform componentKey=${componentPath}`);
+                }
                 return true;
             },
         },
@@ -258,11 +482,140 @@ function createAngularPlugins(opts) {
             experimental: {
                 useAngularCompilationAPI: opts.useAngularCompilationAPI,
             },
-            liveReload: false, // Disable live reload in favor of HMR
+            // `liveReload` is Analog's flag for Angular's web-style template HMR
+            // pipeline. When ON, Analog:
+            //   1. Sets `_enableHmr = true` on the TS compiler so each compiled
+            //      component `.mjs` emits `<ClassName>_HmrLoad` plus an
+            //      `import.meta.hot.on('angular:component-update', ...)` listener.
+            //   2. Registers a `/@ng/component?c=<id>` middleware that serves the
+            //      recompiled template's `_UpdateMetadata` source on demand.
+            //   3. In `handleHotUpdate` for `.html` / `.css` / `.scss` edits, sends
+            //      `server.ws.send('angular:component-update', { id, timestamp })`
+            //      so the runtime can call `ɵɵreplaceMetadata` on the live class —
+            //      swapping the template definition AND walking live LViews to
+            //      recreate matching views in-place. NO Angular reboot, NO route
+            //      navigation.
+            //
+            // Previously this was `false` because the NativeScript HMR pipeline
+            // rebuilt every save through `__reboot_ng_modules__`. That works but
+            // has two big downsides on mobile: every save triggers a full app
+            // reboot AND the captured route-history replay (see
+            // `@nativescript/angular`'s `hmr-route-replay.ts`), which produces 2-3
+            // re-navigations per save and re-instantiates the page component
+            // multiple times. For pure template/style edits — the common case —
+            // the web-style component-replacement path keeps the page mounted and
+            // only swaps the changed bits.
+            //
+            // We only enable this when HMR itself is active (`hmrActive` already
+            // gates on `--hmr` and `NODE_ENV !== 'production'`). With HMR off the
+            // behaviour is unchanged: production builds and `--no-hmr` dev still
+            // see `liveReload: false`, the compiler skips the HMR initializers,
+            // and the middleware is not registered.
+            //
+            // Important interactions to be aware of:
+            //   - When `_enableHmr` is true, Analog also sets
+            //     `externalRuntimeStyles = true`, changing how component styles
+            //     are emitted (URLs fetched at runtime instead of inlined). For
+            //     NativeScript, the existing CSS pipeline expects inlined styles;
+            //     `ns-component-hmr-style-overrides` (below) restores the
+            //     pre-HMR style-emission strategy so Tailwind/global SCSS
+            //     packaging keeps working.
+            //   - The runtime dynamic-import resolves the metadata URL relative
+            //     to `import.meta.url`, e.g. `http://host:port/ns/m/<componentDir>/@ng/component?c=...`.
+            //     Analog's middleware uses `req.url.includes('/@ng/component')`
+            //     (substring match), so the request still matches even with the
+            //     `/ns/m/` prefix in the path.
+            //   - The NS HMR client (`packages/vite/hmr/client/index.ts`)
+            //     forwards Vite's standard `{ type: 'custom', event, data }`
+            //     payloads to `import.meta.hot.on` listeners via
+            //     `__NS_DISPATCH_HOT_EVENT__`, and short-circuits before the
+            //     reboot path for `angular:component-update`.
+            //   - The NS server-side hot-update handler in
+            //     `packages/vite/hmr/server/websocket.ts` skips its own
+            //     `ns:angular-update` broadcast for `.html` / component-style
+            //     edits so we don't double-fire (the reboot path stays for `.ts`
+            //     edits).
+            //   - To roll back to the legacy reboot-only pipeline (e.g. while
+            //     debugging an `externalRuntimeStyles` regression), set
+            //     `NS_VITE_ANGULAR_LIVE_RELOAD=0` in the dev environment.
+            //     `hmrAngularLiveReload` collapses both gates above.
+            liveReload: hmrAngularLiveReload,
+            // NativeScript can't consume Angular's `externalRuntimeStyles`
+            // mode — that emits component styles as runtime-loaded
+            // `<hash>.css` URL references which only a browser CSSOM/`<link>`
+            // pipeline can resolve. We tell our patched Analog plugin (see
+            // `patches/@analogjs+vite-plugin-angular+2.3.1.patch` in
+            // downstream apps; upstream PR pending) to keep the legacy
+            // behavior of inlining preprocessed CSS strings into the
+            // component metadata's `styles: [...]` array, which the NS
+            // renderer's CSS-bundle pipeline already knows how to apply.
+            // The option is independent from `liveReload` (`_enableHmr`
+            // still wires up `ɵɵreplaceMetadata` for in-place template
+            // HMR) — we keep HMR ON, just opt out of the URL-style
+            // emission. Note the option lands as a no-op on stock
+            // Analog releases that haven't merged the patch; once
+            // merged, this will switch the compiler off external styles
+            // for NativeScript without affecting web builds.
+            //
+            // `@ts-expect-error` because the option is not yet in
+            // `@analogjs/vite-plugin-angular`'s published `PluginOptions`
+            // type. When the upstream PR (https://github.com/analogjs/analog)
+            // adds it, this `@ts-expect-error` will itself become an
+            // "unused suppression" error — that's the signal to remove
+            // this comment AND the surrounding explanation, and bump
+            // the Analog peer dep to the version that ships the type.
+            // @ts-expect-error -- pending upstream Analog type publish
+            externalRuntimeStyles: false,
             tsconfig: tsConfig,
+            // Forward Angular-style file replacements (e.g. `environment.ts`
+            // → `environment.stg.ts`) directly into the Analog plugin so the
+            // Angular TypeScript host (which reads source files via its own
+            // CompilerHost, bypassing Vite's load chain) sees the swap. This
+            // is the same hook Angular CLI uses for `fileReplacements` in
+            // `angular.json` build configurations.
+            fileReplacements: opts.fileReplacements ?? [],
+            workspaceRoot: opts.workspaceRoot ?? process.cwd(),
         }),
         // Post-phase linker to catch any declarations introduced after other transforms (including project code)
         angularLinkerVitePluginPost(process.cwd()),
+        // Re-inject the `/* @vite-ignore */` annotation onto Angular's HMR
+        // initializer dynamic imports.
+        //
+        // Angular's compiler emits each component's HMR loader as
+        // `import(/* @vite-ignore */ i0.ɵɵgetReplaceMetadataURL(...))` so
+        // Vite leaves the runtime-computed URL alone. The annotation goes
+        // missing somewhere in the post-Angular pipeline (empirically the
+        // linker's `compact: false` Babel pass loses it on some files),
+        // causing Vite's static analyzer to flag the import and rewrite
+        // the call site through its runtime resolver — which then throws
+        // `TypeError at ɵɵgetReplaceMetadataURL` on the iOS device because
+        // the resolver expects a statically known specifier.
+        //
+        // Running `enforce: 'post'` and `apply: 'serve'` here ensures we
+        // see the file AFTER every other transform has had its chance to
+        // strip comments, AND only in dev (the HMR initializer is gated
+        // behind `ngDevMode` and never runs in a production build, so the
+        // fix would be wasted work outside `serve`). The helper is
+        // idempotent: if the annotation is already present, the file is
+        // returned unchanged.
+        {
+            name: 'ns-angular-hmr-vite-ignore',
+            enforce: 'post',
+            apply: 'serve',
+            transform(code, id) {
+                if (!hmrAngularLiveReload)
+                    return null;
+                const cleanId = id.split('?', 1)[0];
+                if (!cleanId.endsWith('.ts') && !cleanId.endsWith('.mjs') && !cleanId.endsWith('.js'))
+                    return null;
+                if (cleanId.includes('/node_modules/'))
+                    return null;
+                const next = injectAngularHmrViteIgnore(code);
+                if (next === code)
+                    return null;
+                return { code: next, map: null };
+            },
+        },
         // Enforce: fully disable dependency optimization during serve to avoid rxjs esm5 crawling and OOM
         {
             name: 'ns-disable-optimize-deps',
@@ -301,7 +654,7 @@ function createAngularPlugins(opts) {
         },
     ];
 }
-export const angularConfig = ({ mode }) => {
+export const angularConfig = ({ mode, fileReplacements, workspaceRoot, }) => {
     const useSingleBundleDevOutput = mode === 'development' && !hmrActive;
     const plugins = createAngularPlugins({
         // Vite build --watch with the legacy Analog compilation path can regress
@@ -309,6 +662,8 @@ export const angularConfig = ({ mode }) => {
         // Restrict the newer compilation API to NativeScript's development no-HMR
         // flow, which is where the unstable rebuilds occur today.
         useAngularCompilationAPI: useSingleBundleDevOutput,
+        fileReplacements,
+        workspaceRoot,
     });
     const disableAnimations = true;
     //process.env.NS_DISABLE_NG_ANIMATIONS === "1" ||
@@ -375,10 +730,7 @@ export const angularConfig = ({ mode }) => {
                         if (finalCode !== code) {
                             chunk.code = finalCode;
                             if (debug) {
-                                try {
-                                    console.log('[ns-angular-linker][post] linked', fileName, isNsPolyfills ? '(polyfills)' : '');
-                                }
-                                catch { }
+                                console.log('[ns-angular-linker][post] linked', fileName, isNsPolyfills ? '(polyfills)' : '');
                             }
                         }
                         if (strict && !isNsPolyfills && containsRealNgDeclare(finalCode)) {
@@ -424,10 +776,7 @@ export const angularConfig = ({ mode }) => {
                     throw new Error(message);
                 }
                 else {
-                    try {
-                        console.warn(`[ns-angular-linker-post] ${message}`);
-                    }
-                    catch { }
+                    console.warn(`[ns-angular-linker-post] ${message}`);
                 }
             }
         },
@@ -474,10 +823,7 @@ export const angularConfig = ({ mode }) => {
                 transformed = applyAngularChunkPostProcessing(transformed);
                 if (transformed !== code) {
                     if (debug) {
-                        try {
-                            console.log('[ns-angular-linker][render] linked', filename);
-                        }
-                        catch { }
+                        console.log('[ns-angular-linker][render] linked', filename);
                     }
                     return { code: transformed, map: null };
                 }