@servicetitan/startup 36.0.0 → 36.1.1-beta.1

package/src/vite/plugins/__tests__/style-urls-plugin.test.ts

@@ -0,0 +1,76 @@
+import type { BuildContext } from '../../../core';
+import { styleUrlsPlugin } from '../style-urls-plugin';
+
+describe(styleUrlsPlugin.name, () => {
+    let context: BuildContext;
+
+    beforeEach(() => {
+        context = {
+            build: { name: 'test', isProduction: true },
+            package: { isWebComponent: true },
+        } as BuildContext;
+    });
+
+    const subject = () => styleUrlsPlugin(context);
+
+    const itReturnsUndefined = () => {
+        test('returns undefined', () => {
+            expect(subject()).toBeUndefined();
+        });
+    };
+
+    test('returns plugin with correct name', () => {
+        expect(subject()!.name).toBe('style-urls');
+    });
+
+    describe('when package is not a web component', () => {
+        beforeEach(() => (context.package.isWebComponent = false));
+
+        itReturnsUndefined();
+    });
+
+    describe('when build is not production', () => {
+        beforeEach(() => (context.build.isProduction = false));
+
+        itReturnsUndefined();
+    });
+
+    describe('transformIndexHtml', () => {
+        const styleUrlsHtml = (urls: string[]) =>
+            `<web-component style-urls="${encodeURIComponent(JSON.stringify(urls))}">`;
+
+        let bundle: Record<string, { type: string; fileName: string }>;
+
+        beforeEach(() => {
+            bundle = {};
+        });
+
+        const subject = () => {
+            const plugin = styleUrlsPlugin(context)!;
+            const transform = (plugin.transformIndexHtml as any).handler;
+            return transform(styleUrlsHtml([]), { bundle });
+        };
+
+        test('returns html with empty style-urls', () => {
+            expect(subject()).toBe(styleUrlsHtml([]));
+        });
+
+        describe('when bundle has CSS and non-CSS assets', () => {
+            beforeEach(() => {
+                bundle = {
+                    'style.css': { type: 'asset', fileName: 'assets/style-abc123.css' },
+                    'main.js': { type: 'chunk', fileName: 'assets/main-def456.js' },
+                    'other.css': { type: 'asset', fileName: 'assets/other-789.css' },
+                };
+            });
+
+            test('replaces placeholder with CSS file names', () => {
+                const cssFileNames = Object.values(bundle)
+                    .filter(b => b.type === 'asset' && b.fileName.endsWith('.css'))
+                    .map(b => b.fileName);
+
+                expect(subject()).toBe(styleUrlsHtml(cssFileNames));
+            });
+        });
+    });
+});

package/src/vite/plugins/__tests__/svgr-plugin.test.ts

@@ -0,0 +1,67 @@
+import svgr from 'vite-plugin-svgr';
+import type { ViteBuildContext } from '../../types';
+import { svgrPlugin } from '../svgr-plugin';
+
+jest.mock('vite-plugin-svgr', () => jest.fn(() => ({ name: 'vite-plugin-svgr' })));
+
+describe(svgrPlugin.name, () => {
+    let context: ViteBuildContext;
+
+    beforeEach(() => {
+        context = {
+            bundlerConfig: { pluginOverrides: {} },
+        } as ViteBuildContext;
+    });
+
+    const subject = () => svgrPlugin(context);
+
+    test('calls svgr with default include patterns', () => {
+        subject();
+
+        expect(svgr).toHaveBeenCalledWith({
+            include: ['**/*.svg?component', '**/@servicetitan/anvil2/**/*.svg'],
+        });
+    });
+
+    describe('when include is overridden', () => {
+        const include = ['**/*.svg'];
+
+        beforeEach(() => {
+            context.bundlerConfig.pluginOverrides.svgr = { include };
+        });
+
+        test('passes include to svgr', () => {
+            subject();
+
+            expect(svgr).toHaveBeenCalledWith(expect.objectContaining({ include }));
+        });
+    });
+
+    describe('when exclude is overridden', () => {
+        const exclude = ['**/icons/**'];
+
+        beforeEach(() => {
+            context.bundlerConfig.pluginOverrides.svgr = { exclude };
+        });
+
+        test('passes exclude to svgr', () => {
+            subject();
+
+            expect(svgr).toHaveBeenCalledWith(expect.objectContaining({ exclude }));
+        });
+    });
+
+    describe('when svgrOptions is overridden', () => {
+        const svgrOptions = { icon: true };
+
+        beforeEach(() => {
+            context.bundlerConfig.pluginOverrides.svgr = { svgrOptions };
+        });
+
+        test('passes svgrOptions to svgr', () => {
+            subject();
+
+            expect(svgr).toHaveBeenCalledWith(expect.objectContaining({ svgrOptions }));
+        });
+    });
+});

package/src/vite/plugins/__tests__/virtual-modules-plugin.test.ts

@@ -0,0 +1,120 @@
+import path from 'path';
+import { virtualModules } from '../../../core';
+import { virtualModulesPlugin } from '../virtual-modules-plugin';
+
+jest.mock('../../../core', () => ({
+    virtualModules: jest.fn(),
+}));
+
+describe(virtualModulesPlugin.name, () => {
+    const VIRTUAL_PREFIX = '\0VIRTUAL';
+    const indexCode = "import App from './app';\nregister(App, 'my-component');";
+    const designSystemCss = '@import "design-system";';
+
+    let context: any;
+    let modules: { index?: string; designSystem?: string };
+
+    beforeEach(() => {
+        context = {
+            build: { isProduction: true },
+            package: { destination: '/dist', isWebComponent: false },
+        };
+        modules = {};
+        jest.mocked(virtualModules).mockReturnValue(modules);
+    });
+
+    const subject = () => virtualModulesPlugin(context);
+
+    test('returns undefined when no virtual modules exist', () => {
+        expect(subject()).toBeUndefined();
+    });
+
+    describe('when index module exists', () => {
+        beforeEach(() => (modules.index = indexCode));
+
+        test('returns plugin with correct name', () => {
+            expect(subject()!.name).toBe('virtual-modules');
+        });
+
+        describe('resolveId', () => {
+            const subject = () => {
+                const plugin = virtualModulesPlugin(context)!;
+                return (source: string, importer?: string) =>
+                    (plugin.resolveId as Function).call(plugin, source, importer);
+            };
+
+            test('resolves known module to virtual id', () => {
+                expect(subject()('./index')).toBe(`${VIRTUAL_PREFIX}./index`);
+            });
+
+            test('returns undefined for unknown module', () => {
+                expect(subject()('./unknown')).toBeUndefined();
+            });
+
+            test('resolves relative import from virtual module to destination', () => {
+                const result = subject()('./app', `${VIRTUAL_PREFIX}./index`);
+
+                expect(result).toBe(path.resolve('/dist', './app.js'));
+            });
+
+            test('returns undefined for relative import from non-virtual module', () => {
+                expect(subject()('./app', '/src/index.ts')).toBeUndefined();
+            });
+        });
+
+        describe('load', () => {
+            const subject = () => {
+                const plugin = virtualModulesPlugin(context)!;
+                return (id: string) => (plugin.load as Function).call(plugin, id);
+            };
+
+            test('returns module code for virtual id', () => {
+                expect(subject()(`${VIRTUAL_PREFIX}./index`)).toBe(indexCode);
+            });
+
+            test('returns undefined for non-virtual id', () => {
+                expect(subject()('./index')).toBeUndefined();
+            });
+        });
+    });
+
+    describe('when index module exists for dev web component', () => {
+        beforeEach(() => {
+            modules.index = indexCode;
+            context.build.isProduction = false;
+            context.package.isWebComponent = true;
+        });
+
+        test('wraps App with withCssInjector', () => {
+            const plugin = subject()!;
+            const code = (plugin.load as Function).call(plugin, `${VIRTUAL_PREFIX}./index`);
+
+            expect(code).toContain(
+                "import { withCssInjector } from '@servicetitan/web-components'"
+            );
+            expect(code).toContain('const WrappedApp = withCssInjector(App)');
+            expect(code).toContain('register(WrappedApp');
+        });
+    });
+
+    describe('when design system module exists', () => {
+        beforeEach(() => (modules.designSystem = designSystemCss));
+
+        test('resolves design-system.css to virtual id', () => {
+            const plugin = subject()!;
+            const result = (plugin.resolveId as Function).call(plugin, './design-system.css');
+
+            expect(result).toBe(`${VIRTUAL_PREFIX}./design-system.css`);
+        });
+
+        test('loads design system code', () => {
+            const plugin = subject()!;
+            const result = (plugin.load as Function).call(
+                plugin,
+                `${VIRTUAL_PREFIX}./design-system.css`
+            );
+
+            expect(result).toBe(designSystemCss);
+        });
+    });
+});

package/src/vite/plugins/css-injector-plugin.ts

@@ -0,0 +1,60 @@
+import type { Plugin } from 'vite';
+import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js';
+import type { BuildContext } from '../../core';
+
+/*
+ * injectCodeFunction is serialized to a string and runs in the browser —
+ * it cannot reference outer scope or imports.
+ * It communicates with with-css-injector.tsx via window.__mfeStyles__.
+ *
+ * The plugin creates CSSStyleSheet objects and stores them in emitter.sheets.
+ * HMR updates call replaceSync() on existing sheets — all shadow roots that
+ * adopted the sheet see the update automatically (shared reference).
+ * Events are only dispatched for new sheets so the injector can adopt them.
+ *
+ * removeStyleCodeFunction is not needed: CSS HMR calls inject with updated CSS,
+ * and replaceSync() overwrites the existing CSSStyleSheet in place.
+ * If JS HMR is ever added, removeStyleCodeFunction would be needed to clean up
+ * styles when a source file drops a CSS import (e.g. removing `import './button.css'`).
+ * Without JS HMR, that change triggers a full page reload, so cleanup is automatic.
+ */
+export function cssInjectorPlugin(context: BuildContext): Plugin[] {
+    const { name, isProduction } = context.build;
+    const { isWebComponent } = context.package;
+    if (isWebComponent && !isProduction) {
+        return cssInjectedByJsPlugin({
+            dev: { enableDev: true },
+            styleId: name,
+            /*
+             * Serialized to a string and executed in the browser at runtime — uses
+             * constructable CSSStyleSheet which jsdom does not support, and .toString()
+             * serialization means a Node.js unit test wouldn't catch closure or scope issues.
+             */
+            injectCodeFunction: /* istanbul ignore next */ function injectWebComponentStyles(
+                css,
+                { styleId, attributes }
+            ) {
+                const componentName = styleId as string;
+                const sheetId = attributes!['data-vite-dev-id'];
+                window.__mfeStyles__ ??= {};
+                const mfeStyles = window.__mfeStyles__;
+                mfeStyles[componentName] ??= Object.assign(new EventTarget(), {
+                    sheets: new Map(),
+                });
+                const emitter = mfeStyles[componentName];
+                let sheet = emitter.sheets.get(sheetId);
+                if (sheet) {
+                    sheet.replaceSync(css);
+                } else {
+                    sheet = new CSSStyleSheet();
+                    sheet.replaceSync(css);
+                    emitter.sheets.set(sheetId, sheet);
+                    emitter.dispatchEvent(
+                        new CustomEvent<string>('new-sheet', { detail: sheetId })
+                    );
+                }
+            },
+        });
+    }
+    return [];
+}

package/src/vite/plugins/dev-server-routing-plugin.ts

@@ -0,0 +1,96 @@
+import fs from 'fs';
+import path from 'path';
+import type { Plugin } from 'vite';
+import { getBundleType, type BuildContext } from '../../core';
+import { log } from '../../utils';
+
+/**
+ * URL rewrites for dev and preview servers.
+ *
+ * Dev serves from the project root, preview serves from outDir. Production builds output to
+ * dist/bundle/. Paths that work in prod (relative to index.html in outDir) break in dev and
+ * preview because the server root differs.
+ *
+ * - Host dev (root: project root): template uses ./shared/... which resolves to /shared/...
+ *   but files are at dist/bundle/shared/. Rewrites to /dist/bundle/shared/... so Vite serves them.
+ *
+ * - MFE dev (root: project root): Loader reads entrypoints.json and requests assets at
+ *   production output paths (e.g. /dist/bundle/full/index.js). Strips the outDir prefix
+ *   so files resolve from root.
+ *
+ * - Host preview (root: dist/bundle/): shared/ is inside outDir, no rewrites needed.
+ *
+ * - MFE preview (root: dist/bundle/full/): host requests metadata.json from the parent
+ *   dist/bundle/ and sibling bundle assets (light/, headless/). Serves the entire destination
+ *   directory as static files.
+ */
+export function devServerRoutingPlugin(context: BuildContext): Plugin {
+    const { isWebComponent, destination } = context.package;
+    let outDir = '';
+
+    const sharedDepsDirname = getBundleType({
+        ...context,
+        build: { ...context.build, emitExposedDependencies: true },
+    });
+
+    const logRequest = (req: import('http').IncomingMessage) => {
+        log.info(`[${log.timestamp}]: ${req.method} ${req.url}`);
+    };
+
+    return {
+        name: 'dev-server-routing',
+
+        configResolved(config) {
+            outDir = config.build.outDir;
+        },
+
+        configureServer(server) {
+            const outDirRelative = `/${path.relative(process.cwd(), outDir)}/`;
+
+            server.middlewares.use((req, _res, next) => {
+                logRequest(req);
+                const url = req.url ?? '';
+                if (isWebComponent) {
+                    if (url.startsWith(outDirRelative)) {
+                        req.url = url.slice(outDirRelative.length - 1);
+                    }
+                } else if (url.startsWith(`/${sharedDepsDirname}/`)) {
+                    req.url = `${outDirRelative}${url.slice(1)}`;
+                }
+                next();
+            });
+        },
+
+        configurePreviewServer(server) {
+            server.middlewares.use((req, _res, next) => {
+                logRequest(req);
+                next();
+            });
+
+            if (!isWebComponent) {
+                return;
+            }
+
+            const destDir = path.resolve(destination);
+            const mountPath = '/' + path.relative(process.cwd(), destDir);
+
+            const contentTypes: Record<string, string> = {
+                '.js': 'application/javascript',
+                '.css': 'text/css',
+                '.json': 'application/json',
+            };
+
+            server.middlewares.use(mountPath, (req, res, next) => {
+                const filePath = path.join(destDir, req.url ?? '');
+                if (!filePath.startsWith(destDir + path.sep) || !fs.existsSync(filePath)) {
+                    return next();
+                }
+                const contentType = contentTypes[path.extname(filePath)];
+                if (contentType) {
+                    res.setHeader('Content-Type', contentType);
+                }
+                fs.createReadStream(filePath).pipe(res);
+            });
+        },
+    };
+}

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

@@ -0,0 +1,81 @@
+import fs from 'fs';
+import path from 'path';
+import type { Plugin } from 'vite';
+import { BuildContext, getExternals } from '../../core';
+
+/*
+ * Externalizes shared dependencies by redirecting imports to CJS proxy modules
+ * that read from the host's global shared deps registry at runtime.
+ *
+ * Each shared dep gets a fake package on disk (node_modules/.startup/externals/)
+ * with `module.exports = SharedDependencies.Foo['scope']`.
+ *
+ * Three mechanisms work together, each handling a different mode:
+ *
+ * - resolve.alias (dev) — exact-match regex redirects `react` to the proxy package.
+ *   Subpath imports (react/jsx-runtime) are NOT matched and resolve normally.
+ *
+ * - optimizeDeps.include (dev) — forces Vite to pre-bundle the proxy packages.
+ *   This triggers Vite's CJS-to-ESM interop: the pre-bundled output has `export default`,
+ *   and Vite's import-analysis plugin rewrites consumers' named imports to property access
+ *   on the default export (e.g. `import { useState } from 'react'` becomes
+ *   `const useState = __default["useState"]`). Without optimizeDeps, the raw CJS proxy
+ *   would be served to the browser and fail on named imports.
+ *
+ * - resolveId (prod) — resolve.alias doesn't run during Rolldown bundling, so resolveId
+ *   with enforce:'pre' intercepts shared dep imports before Vite's default resolver.
+ *   Rolldown handles CJS-to-ESM interop natively via __commonJSMin/__toESM helpers.
+ *   Only exact matches — subpath imports must NOT be redirected because they export
+ *   different things than the barrel.
+ *
+ * The disk-based proxy + optimizeDeps complexity exists because Vite's dev server serves
+ * modules as native ESM without bundling — CJS virtual modules can't be served to the browser.
+ * When Vite's "full bundle" dev mode ships (Rolldown bundles in dev, like prod), this can be
+ * simplified to a single resolveId + load with a virtual CJS module for both modes (see 9ffd1815).
+ */
+export function externalsPlugin(context: BuildContext): Plugin | undefined {
+    const entries = getExternals(context);
+    if (!entries) {
+        return;
+    }
+
+    const proxyModulesDir = path.resolve('node_modules', '.startup', 'externals');
+    for (const [dep, proxy] of Object.entries(entries)) {
+        const pkgDir = path.join(proxyModulesDir, 'node_modules', dep);
+        fs.mkdirSync(pkgDir, { recursive: true });
+        fs.writeFileSync(path.join(pkgDir, 'index.cjs'), `module.exports = ${proxy};`);
+        fs.writeFileSync(
+            path.join(pkgDir, 'package.json'),
+            JSON.stringify({ name: dep, main: './index.cjs' })
+        );
+    }
+
+    const proxyNodeModules = path.join(proxyModulesDir, 'node_modules');
+
+    const { isProduction } = context.build;
+
+    return {
+        name: 'externals',
+        enforce: 'pre',
+        config: isProduction
+            ? undefined
+            : () => ({
+                  resolve: {
+                      alias: Object.keys(entries).map(dep => ({
+                          find: new RegExp(`^${dep.replace('/', '\\/')}$`),
+                          replacement: path.join(proxyNodeModules, dep),
+                      })),
+                  },
+                  optimizeDeps: {
+                      include: Object.keys(entries),
+                  },
+              }),
+        resolveId: isProduction
+            ? (source: string) => {
+                  if (source in entries) {
+                      return path.join(proxyNodeModules, source, 'index.cjs');
+                  }
+              }
+            : undefined,
+    };
+}

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

@@ -0,0 +1,94 @@
+import { Eta } from 'eta';
+import fs from 'fs';
+import path from 'path';
+import type { Plugin } from 'vite';
+import { getSharedEntryPoints } from '../../core';
+import { ViteBuildContext } from '../types';
+
+export function htmlPlugin(context: ViteBuildContext): Plugin {
+    const { name, isProduction } = context.build;
+    const { isWebComponent } = context.package;
+    const { css, js } = getSharedEntryPoints(context);
+    const { pluginOverrides } = context.bundlerConfig;
+
+    const htmlTemplatePath = pluginOverrides.html?.template
+        ? path.resolve(pluginOverrides.html.template)
+        : path.resolve(__dirname, '../index.html');
+
+    const eta = new Eta({ views: path.dirname(htmlTemplatePath) });
+
+    let detectedFavicon: string | undefined;
+
+    function renderHtml() {
+        return eta.render(path.basename(htmlTemplatePath), {
+            title: pluginOverrides.html?.title ?? 'ServiceTitan',
+            favicon: pluginOverrides.html?.favicon ?? detectedFavicon,
+            css,
+            js,
+            isProduction,
+            isWebComponent,
+            name,
+        });
+    }
+
+    /*
+     * Virtual entry point for the HTML module. The file doesn't exist on disk —
+     * resolveId claims this path and load returns Eta-rendered HTML.
+     *
+     * Uses an absolute path (e.g., /path/to/project/index.html) instead of a
+     * synthetic prefix because Vite resolves asset references in HTML (favicon,
+     * CSS links) relative to the HTML file's directory. A non-filesystem path
+     * would break those references.
+     */
+    const INDEX_HTML = 'index.html';
+    const VIRTUAL_HTML_PATH = path.resolve(INDEX_HTML);
+
+    return {
+        name: 'html',
+        /*
+         * Auto-detect favicon.ico in vite's publicDir so projects following
+         * the convention get a working favicon link without explicit config.
+         */
+        configResolved(config) {
+            if (config.publicDir && fs.existsSync(path.join(config.publicDir, 'favicon.ico'))) {
+                detectedFavicon = '/favicon.ico';
+            }
+        },
+        /*
+         * Dev server serves HTML via middleware (load is not called in dev mode).
+         * Returns a callback so middleware registers after Vite's built-in middleware.
+         */
+        configureServer(server) {
+            return () => {
+                server.middlewares.use(async (req, res, next) => {
+                    if (!req.url?.endsWith(INDEX_HTML)) {
+                        return next();
+                    }
+                    let html = renderHtml();
+                    html = await server.transformIndexHtml(req.url, html);
+                    res.end(html);
+                });
+            };
+        },
+        resolveId(source: string, importer: string | undefined) {
+            /*
+             * Claim the HTML entry so Vite doesn't look for it on disk (it's virtual, rendered by Eta).
+             * Only needed for production builds — dev mode serves HTML via configureServer middleware.
+             */
+            if (source === VIRTUAL_HTML_PATH) {
+                return VIRTUAL_HTML_PATH;
+            }
+            if (importer?.includes(INDEX_HTML) && source.startsWith('.')) {
+                const resolved = path.resolve(source + '.js');
+                if (fs.existsSync(resolved)) {
+                    return resolved;
+                }
+            }
+        },
+        load(id: string) {
+            if (id === VIRTUAL_HTML_PATH) {
+                return renderHtml();
+            }
+        },
+    };
+}

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

@@ -0,0 +1,22 @@
+import type { Plugin } from 'vite';
+import { BuildContext, checkResource } from '../../core';
+
+export function ignoreModulesPlugin(context: BuildContext): Plugin {
+    const VIRTUAL_PREFIX = '\0IGNORE';
+
+    const checker = checkResource(context);
+
+    return {
+        name: 'ignore-modules',
+        resolveId(source, importer) {
+            if (importer && checker(source, importer)) {
+                return `${VIRTUAL_PREFIX}${source}`;
+            }
+        },
+        load(id) {
+            if (id.startsWith(VIRTUAL_PREFIX)) {
+                return 'export default {}';
+            }
+        },
+    };
+}

package/src/vite/plugins/index.ts

@@ -0,0 +1,9 @@
+export * from './css-injector-plugin';
+export * from './dev-server-routing-plugin';
+export * from './externals-plugin';
+export * from './html-plugin';
+export * from './ignore-modules-plugin';
+export * from './metadata-plugin';
+export * from './style-urls-plugin';
+export * from './svgr-plugin';
+export * from './virtual-modules-plugin';