@servicetitan/startup 38.0.0 → 38.2.0

package/src/vite/plugins/ignore-modules-plugin.ts

@@ -2,8 +2,11 @@ import type { Plugin } from 'vite';
 import { checkResource } from '../../core';
 import type { PackageContext } from '../../core/types';
 
-export const THROW_PREFIX = '\0IGNORE_THROW:';
-export const EMPTY_PREFIX = '\0IGNORE_EMPTY:';
+const VIRTUAL_PREFIX = '\0ignore-modules:';
+const VIRTUAL_ID_PATTERN = new RegExp(`^${VIRTUAL_PREFIX}`);
+
+export const THROW_PREFIX = `${VIRTUAL_PREFIX}throw:`;
+export const EMPTY_PREFIX = `${VIRTUAL_PREFIX}empty:`;
 
 /**
  * Handles optional peer dependencies that are not installed.
@@ -26,29 +29,35 @@ export function ignoreModulesPlugin(context: {
     const checker = checkResource(context);
 
     return {
-        name: 'ignore-modules',
+        name: 'st:ignore-modules',
         enforce: 'pre',
-        resolveId(source, importer) {
-            if (!importer) {
-                return;
-            }
-            const mode = checker({ resource: source, importer });
-            if (mode === 'throw') {
-                return `${THROW_PREFIX}${source}`;
-            }
-            if (mode === 'empty') {
-                return `${EMPTY_PREFIX}${source}`;
-            }
+        resolveId: {
+            filter: { id: /^[@a-z]/ }, // Only bare specifiers can be optional peers
+            handler(source, importer) {
+                if (!importer) {
+                    return;
+                }
+                const mode = checker({ resource: source, importer });
+                if (mode === 'throw') {
+                    return `${THROW_PREFIX}${source}`;
+                }
+                if (mode === 'empty') {
+                    return `${EMPTY_PREFIX}${source}`;
+                }
+            },
         },
-        load(id) {
-            if (id.startsWith(THROW_PREFIX)) {
-                const source = id.slice(THROW_PREFIX.length);
-                const message = JSON.stringify(`Cannot find module '${source}'`);
-                return `throw Object.assign(new Error(${message}), { code: 'MODULE_NOT_FOUND' });`;
-            }
-            if (id.startsWith(EMPTY_PREFIX)) {
-                return 'export {};';
-            }
+        load: {
+            filter: { id: VIRTUAL_ID_PATTERN },
+            handler(id) {
+                if (id.startsWith(THROW_PREFIX)) {
+                    const source = id.slice(THROW_PREFIX.length);
+                    const message = JSON.stringify(`Cannot find module '${source}'`);
+                    return `throw Object.assign(new Error(${message}), { code: 'MODULE_NOT_FOUND' });`;
+                }
+                if (id.startsWith(EMPTY_PREFIX)) {
+                    return 'export {};';
+                }
+            },
         },
     };
 }

package/src/vite/plugins/index.ts

@@ -8,9 +8,12 @@ export * from './externals-plugin';
 export * from './html-plugin';
 export * from './ignore-modules-plugin';
 export * from './istanbul-plugin';
+export * from './less-tilde-plugin';
 export * from './magic-comments-plugin';
 export * from './metadata-plugin';
 export * from './moment-locales-plugin';
+export * from './react-refresh-plugin';
 export * from './style-urls-plugin';
 export * from './svgr-plugin';
 export * from './virtual-modules-plugin';
+export * from './window-externals-plugin';

package/src/vite/plugins/less-tilde-plugin.ts

@@ -0,0 +1,64 @@
+import fs from 'fs';
+import path from 'path';
+import { findUp } from '../../utils';
+
+interface LessPluginManager {
+    addFileManager(manager: unknown): void;
+}
+
+/*
+ * Less plugin that resolves webpack-style `~pkg` imports (e.g. `~@servicetitan/tokens/...`) from
+ * node_modules. Vite's Less integration does not understand the `~` prefix, so without this every
+ * style importing a package with `~` fails to resolve. Mirrors the old less-loader behavior to
+ * ease webpack-to-Vite migration.
+ */
+export function lessTildePlugin() {
+    return {
+        install(less: any, pluginManager: LessPluginManager) {
+            const TildeFileManager = createTildeFileManager(less);
+            pluginManager.addFileManager(new TildeFileManager());
+        },
+    };
+}
+
+/*
+ * A FileManager subclass bound to the Less instance Vite passes to the plugin. It claims `~`
+ * imports and rewrites them to a node_modules path before delegating to the base loader.
+ */
+function createTildeFileManager(less: any) {
+    return class extends less.FileManager {
+        supports(filename: string) {
+            return filename.startsWith('~');
+        }
+
+        loadFile(
+            filename: string,
+            currentDirectory: string,
+            options: unknown,
+            environment: unknown
+        ) {
+            return super.loadFile(
+                resolveFromNodeModules(filename.slice(1), currentDirectory),
+                currentDirectory,
+                options,
+                environment
+            );
+        }
+    };
+}
+
+/*
+ * Resolve a bare `pkg/path` specifier against the nearest node_modules, walking up from the
+ * importing file's directory, so the import binds to the importer's dependencies (matching
+ * webpack, and covering both pnpm's symlinked store and npm's hoisted tree).
+ */
+function resolveFromNodeModules(specifier: string, fromDirectory: string): string {
+    const withExtension = path.extname(specifier) ? specifier : `${specifier}.less`;
+
+    const resolved = findUp(directory => {
+        const candidate = path.join(directory, 'node_modules', withExtension);
+        return fs.existsSync(candidate) ? candidate : undefined;
+    }, fromDirectory);
+
+    return resolved ?? withExtension;
+}

package/src/vite/plugins/magic-comments-plugin/magic-comments-plugin.ts

@@ -19,7 +19,7 @@ export function magicCommentsPlugin(context: ViteBuildContext): Plugin | undefin
     const moduleByName = new Map<string, string>();
 
     return {
-        name: 'magic-comments',
+        name: 'st:magic-comments',
         apply: 'build',
         enforce: 'pre',
         config: () => ({

package/src/vite/plugins/metadata-plugin.ts

@@ -12,7 +12,7 @@ export function metadataPlugin(context: BuildContext): Plugin | undefined {
     let outDir = '';
 
     return {
-        name: 'metadata',
+        name: 'st:metadata',
         configResolved(config) {
             outDir = config.build.outDir;
         },

package/src/vite/plugins/moment-locales-plugin.ts

@@ -1,7 +1,8 @@
 import type { Plugin } from 'vite';
 import { BuildContext, MOMENT_LOCALES } from '../../core';
 
-export const VIRTUAL_MOMENT = '\0VIRTUAL_MOMENT';
+export const VIRTUAL_MOMENT = '\0moment-locales';
+const VIRTUAL_ID_PATTERN = new RegExp(`^${VIRTUAL_MOMENT}`);
 
 const UMD_LOCALE = /^moment\/locale\/(.+)$/;
 
@@ -15,27 +16,36 @@ const UMD_LOCALE = /^moment\/locale\/(.+)$/;
  */
 export function momentLocalesPlugin(_context: BuildContext): Plugin {
     return {
-        name: 'moment-locales',
+        name: 'st:moment-locales',
         enforce: 'pre',
-        resolveId(source, importer, options) {
-            if (source === 'moment') {
-                return VIRTUAL_MOMENT;
-            }
-            // Redirect explicit UMD locale imports to the ESM build so they share that instance.
-            const locale = UMD_LOCALE.exec(source)?.[1];
-            if (locale) {
-                return this.resolve(`moment/dist/locale/${locale}`, importer, options);
-            }
+        resolveId: {
+            filter: { id: [/^moment$/, UMD_LOCALE] },
+            handler(source, importer, options) {
+                if (source === 'moment') {
+                    return VIRTUAL_MOMENT;
+                }
+                // Redirect explicit UMD locale imports to the ESM build so they share that instance.
+                const locale = UMD_LOCALE.exec(source)?.[1];
+                if (locale) {
+                    return this.resolve(`moment/dist/locale/${locale}`, importer, options);
+                }
+            },
         },
-        load(id) {
-            if (id === VIRTUAL_MOMENT) {
+        load: {
+            filter: { id: VIRTUAL_ID_PATTERN },
+            handler() {
                 return [
                     ...MOMENT_LOCALES.map(locale => `import 'moment/dist/locale/${locale}';`),
                     `import moment from 'moment/dist/moment.js';`,
                     `export * from 'moment/dist/moment.js';`,
                     `export default moment;`,
+                    /*
+                     * moment attaches these to the function itself rather than declaring them as
+                     * real ES named exports, so `export *` above doesn't forward them.
+                     */
+                    `export const isMoment = moment.isMoment;`,
                 ].join('\n');
-            }
+            },
         },
     };
 }

package/src/vite/plugins/react-refresh-plugin/README.md

@@ -0,0 +1,165 @@
+# React Fast Refresh Plugin
+
+This plugin bridges Startup's Vite development build with Vite HMR and React Fast Refresh.
+
+In Vite development mode, `swc` compiles TSX into `dist/` and injects React Fast Refresh markers into modules that contain statically identifiable React components. Vite serves those compiled files, but the markers are just global function calls until something provides the refresh runtime and tells Vite which modules can accept hot updates. This plugin provides that missing serve-time layer.
+
+## Responsibilities
+
+The React Fast Refresh flow has four layers:
+
+| Layer   | Tool                       | Role                                                                                                                                         |
+| ------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Compile | `swc`                      | Compiles TSX to JS in `dist/` and injects `$RefreshReg$` and `$RefreshSig$` markers.                                                         |
+| Serve   | Vite                       | Serves `dist/`, transforms modules, and sends HMR updates over WebSocket.                                                                    |
+| Bridge  | `react-refresh-plugin`     | Serves the refresh runtime, installs it into React's global hook, injects per-module locals, and validates refresh boundaries before update. |
+| Render  | React Fast Refresh runtime | Tracks component families and asks React to re-render with updated component functions.                                                      |
+
+Plain CSS does not use React Fast Refresh. Vite handles plain CSS HMR natively by replacing the stylesheet in the DOM. CSS modules export class name bindings, so they behave more like JS modules and propagate through the importing React module.
+
+## What `swc` Provides
+
+When `react.refresh` and `react.development` are enabled, `swc` emits markers like this:
+
+```js
+var _s = $RefreshSig$();
+export const App = () => {
+    _s();
+    return _jsx('div', { children: '...' });
+};
+_s(App, 'useState{[count, setCount]}');
+$RefreshReg$(App, 'App');
+```
+
+`$RefreshSig$` records the component's hook signature so React can decide whether state can be preserved. `$RefreshReg$` registers the component with a stable ID so the runtime can match the old and new component functions across edits.
+
+`swc` can only register components it can statically identify. A direct function declaration or an arrow function assigned to a variable can be registered. A component returned from a higher-order function call, such as `provide({...})(() => ...)`, cannot. Those modules may get `$RefreshSig$` without `$RefreshReg$`, and this plugin lets those fall through to a full page reload because the runtime cannot track their component identity.
+
+## What The Plugin Does
+
+The plugin runs with `enforce: 'pre'` so its refresh transforms run before Vite's normal transform pipeline. Its transform hook is also filtered to modules whose code contains `$RefreshReg$` or `$RefreshSig$`, so Vite can skip invoking it for unrelated modules.
+
+The plugin does three things in development:
+
+1. It serves `react-refresh/runtime` as a virtual ESM module at `/@react-refresh`.
+2. It injects a preamble script into the HTML head before app code runs.
+3. It transforms served modules that contain refresh markers.
+
+The virtual module wraps the official `react-refresh/runtime` package, stores it on `window.__ReactRefreshRuntime`, and appends local browser helpers from `refresh-runtime.js`. This global singleton matters in the monorepo because the host and MFE can be served by different Vite dev servers. Reusing one runtime ensures `performReactRefresh()` from an MFE update can reach the renderer captured when the host initialized React.
+
+The preamble is a single side-effect import of the virtual module (`import "/@react-refresh"`). Importing the virtual module as a side effect is enough: the module's own initialization code calls `injectIntoGlobalHook(window)` the first time it loads (see `getRefreshRuntimeCode`), which patches `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` so that React registers its renderer with the refresh runtime when React itself initializes. The preamble does not set `window.$RefreshReg$` or `window.$RefreshSig$`. Those are instead injected as per-module locals by the transform step (see below).
+
+The preamble is injected with `injectTo: 'head-prepend'` as a module script. Shared dependency bundles are loaded with `defer`. Module scripts and defer scripts share the same execution queue and run in document order, so the preamble runs before React initializes. That timing ensures `injectIntoGlobalHook` patches the DevTools hook before React calls `hook.inject(renderer)`.
+
+For each served module with `$RefreshReg$` or `$RefreshSig$`, the transform step applies these rules:
+
+- Workspace package modules always receive a per-module prelude that defines local `$RefreshReg$` and `$RefreshSig$` variables. The local `$RefreshReg$` scopes registration IDs to the served module URL so host and MFE servers sharing one runtime cannot produce colliding refresh families. Modules with `$RefreshReg$` additionally receive an HMR postlude that records the current exports and self-accepts future updates.
+- Accepted updates are validated before React Fast Refresh runs. If the module remains a safe refresh boundary, the helper queues `RefreshRuntime.performReactRefresh()`. If exports were added, removed, changed incompatibly, or exposed through getters, the helper calls `import.meta.hot.invalidate(...)` so Vite falls back to normal invalidation and full reload when needed.
+- Workspace modules with only `$RefreshSig$` (HOC-wrapped components) receive the per-module prelude but not the postlude, so they are not self-accepted and Vite falls back to a full reload.
+- Non-workspace library modules shadow `$RefreshReg$` and `$RefreshSig$` with no-ops.
+
+The non-workspace library no-ops avoid duplicate registrations for third-party code that Startup does not own. Workspace package modules are allowed to register because their IDs are scoped to the served runtime URL, so the same local package can be loaded by multiple Vite servers without colliding.
+
+The transform returns a normal source map for the code it changes. Vite decides whether to emit, inline, hide, or drop that map based on the application's source map config. This plugin does not require a specific source map mode, but it can only map back to the JavaScript it receives. Mapping all the way back to the original TSX source still depends on earlier compile steps, such as `swc`, providing their own maps for Vite to chain.
+
+## Key Decisions
+
+### Why `swc` Is Not Enough
+
+`swc` only emits compile-time markers. It does not provide the browser runtime that implements `$RefreshReg$` and `$RefreshSig$`, and it does not tell Vite which JS modules can accept hot updates. Without this plugin, the compiled markers are just global calls with nothing reliable behind them.
+
+The plugin supplies the serve-time pieces that `swc` does not own:
+
+1. Load the official React Fast Refresh runtime.
+2. Install the refresh globals before application modules execute.
+3. Mark modules with registered component families as candidate self-accepting HMR boundaries.
+4. Validate each accepted update against the previous module exports.
+5. Trigger `performReactRefresh()` for compatible boundaries, or invalidate incompatible ones so Vite can reload.
+
+The refresh call is debounced from the HMR accept callback. This lets the accepted module finish evaluating and register its new component family before React Fast Refresh compares families and asks React to re-render.
+
+### Why Boundary Validation Is Required
+
+Seeing `$RefreshReg$` in a module is not enough to prove every export can safely Fast Refresh. A module can register one component while exporting another value that React Fast Refresh cannot track, such as a component returned from a higher-order function call:
+
+```tsx
+export const App = provide({...})(() => <div />);
+```
+
+`swc` cannot register that `App` export as a component family. If the plugin blindly self-accepted the module, Vite would apply the update but React Fast Refresh would have no family to swap, leaving the browser stale. The runtime helper follows Vite React's boundary validation model instead: compatible component exports refresh, unchanged non-component exports are allowed, and incompatible export changes invalidate the module.
+
+For an incompatible export, the browser console shows an invalidation message like:
+
+```text
+[vite] invalidate /dist/app.js: Could not Fast Refresh ("App" export is incompatible).
+```
+
+That full reload fallback is intentional. The contract is that edits either Fast Refresh or reload, but never silently no-op.
+
+### Why The Runtime Helpers Are A JavaScript Sidecar
+
+The `/@react-refresh` virtual module must execute in the browser as ESM. The boundary helpers live in `refresh-runtime.js` and are copied to `dist/` as a normal JavaScript resource, then read into the virtual module at serve time.
+
+Keeping the helpers in a source `.js` sidecar avoids compiling them through Startup's CommonJS package build, which would rewrite browser dynamic imports into `require(...)`. The helper's dynamic import intentionally stays as native browser ESM:
+
+```js
+import(/* @vite-ignore */ module);
+```
+
+### Why The Runtime Is A Global Singleton
+
+Startup can run a host and an MFE from separate Vite dev servers, such as the host on `localhost:8080` and the MFE on `localhost:8888`. The MFE is still rendered by React inside the host page, so refresh updates from the MFE need to reach the renderer and roots captured when the host initialized React.
+
+If each Vite server imported its own refresh runtime instance, an MFE update could call `performReactRefresh()` on a runtime that did not capture the host renderer. The virtual module stores the runtime on `window.__ReactRefreshRuntime` so all dev servers in the same page share the same runtime instance.
+
+### Why Registration IDs Are Scoped To Runtime Module URLs
+
+`swc` emits registration IDs from local component names, such as `"Routes"`. In a host/MFE page, different Vite servers can load different modules that contain components with the same local name. Because those servers intentionally share one runtime singleton, bare component names can collide and make React Fast Refresh treat unrelated host and MFE components as the same family.
+
+Rather than rewriting each `$RefreshReg$(type, "Name")` call, the transform injects a per-module `$RefreshReg$` local that captures the module URL at definition time:
+
+```js
+const __react_refresh_id__ = import.meta.url.replace(/[?#].*$/, '');
+var $RefreshReg$ = (type, id) => RefreshRuntime.register(type, __react_refresh_id__ + ' ' + id);
+```
+
+The query is stripped so the ID stays stable across Vite timestamp updates, but host and MFE servers still get different IDs for the same workspace file because their served URLs differ.
+
+This matters for workspace libraries too. The host and MFE can both load `packages/web-components/dist/loader.js` into the same browser page. Scoping by runtime URL lets both servers register `Loader` without sharing one refresh family, while still allowing edits to `web-components` to update through React Fast Refresh instead of a full page reload.
+
+### Why Non-Workspace Library Markers Are No-Ops
+
+Third-party libraries can be served through Vite as files outside the workspace packages directory. Startup does not compile or control their React Fast Refresh markers, so the plugin shadows `$RefreshReg$` and `$RefreshSig$` with no-ops for those modules. This keeps third-party code from registering duplicate or stale refresh families in the shared runtime.
+
+Workspace modules receive real per-module locals instead of no-ops, so only third-party code is silenced.
+
+### Cross-Bundler Development (Webpack Host + Vite MFE)
+
+React Fast Refresh requires `injectIntoGlobalHook(window)` to run before React initializes. In a Vite host this is guaranteed by the head-prepend preamble. In a webpack host there is no Vite preamble, so React loads from the shared webpack bundle before any Vite module runs. By the time the Vite MFE's first module imports `/@react-refresh` and calls `injectIntoGlobalHook`, React has already initialized without a hook, `hook.renderers` is empty, and `performReactRefresh()` silently no-ops — the browser accepts the HMR update but nothing visibly changes.
+
+## TSX Edit Flow
+
+When a TSX file changes:
+
+1. `swc` recompiles the source file to `dist/` with fresh refresh markers.
+2. Vite detects the changed compiled module.
+3. If this plugin appended an HMR postlude, Vite treats the module as a candidate self-accepting boundary.
+4. The browser re-executes the module. The per-module `$RefreshReg$` local registers component families with URL-scoped stable IDs.
+5. The HMR postlude compares the previous and next module exports.
+6. For compatible boundaries, the runtime stores the update for each component family and queues `RefreshRuntime.performReactRefresh()`.
+7. React swaps `family.current` to the new function, compares hook signatures, and re-renders mounted roots.
+
+If boundary validation fails, the postlude invalidates the module instead. Vite then propagates the update to importers and reloads the page if no valid parent boundary accepts it.
+
+If the hook signature is compatible, React preserves state by reusing the existing fiber and hook slots. If hooks were added, removed, or reordered, React remounts that component so state slots do not get reused incorrectly.
+
+## CSS Edit Flow
+
+Plain CSS imports take Vite's native CSS HMR path:
+
+1. The CSS source changes and Startup copies it to `dist/`.
+2. Vite detects the changed CSS file.
+3. Vite's CSS transform emits an update that calls its stylesheet replacement logic.
+4. The browser updates the stylesheet without involving React Fast Refresh.
+
+CSS modules are different because they export a class-name mapping object. Updates to a CSS module propagate to the importing React module, and React Fast Refresh handles the re-render path for that importer.