@servicetitan/startup 36.3.1 → 37.0.0

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

@@ -0,0 +1,65 @@
+import type { Plugin } from 'vite';
+import type { BuildContext } from '../../core';
+
+/*
+ * Replaces Vite's default CSS injection (<style> tags in document.head) with
+ * MfeStyleRegistry.injectSheet() from @servicetitan/web-components, which
+ * creates CSSStyleSheet objects that can be adopted into shadow roots.
+ *
+ * Works by transforming Vite's CSS module output at enforce:'post'. Vite
+ * transforms CSS imports into JS modules that call updateStyle(id, css) from
+ * /@vite/client — this plugin replaces that call with injectSheet().
+ *
+ * HMR works automatically: when a CSS file changes, Vite re-evaluates the
+ * module, which re-runs injectSheet(). Existing CSSStyleSheet objects are
+ * updated via replaceSync(), so all shadow roots that adopted them see the
+ * change immediately.
+ */
+export function cssInjectorPlugin(context: BuildContext): Plugin | undefined {
+    const { name, isProduction } = context.build;
+    const { isWebComponent } = context.package;
+    if (!isWebComponent || isProduction) {
+        return;
+    }
+
+    return {
+        name: 'mfe-css-injector',
+        enforce: 'post',
+        transform(code, id) {
+            if (!id.endsWith('.css') && !id.endsWith('.less') && !id.endsWith('.scss')) {
+                return;
+            }
+            if (!code.includes('__vite__updateStyle')) {
+                return;
+            }
+
+            let transformed = code;
+
+            const importPattern =
+                /import \{ updateStyle as __vite__updateStyle, removeStyle as __vite__removeStyle \} from [^\n]+/;
+            const callPattern = '__vite__updateStyle(__vite__id, __vite__css)';
+
+            if (!importPattern.test(transformed) || !transformed.includes(callPattern)) {
+                this.error(
+                    `[startup] Failed to transform CSS module — Vite's internal output format may have changed. File: ${id}`
+                );
+            }
+
+            transformed = transformed
+                .replace(
+                    importPattern,
+                    `import { MfeStyleRegistry as __mfe__Registry } from '@servicetitan/web-components'`
+                )
+                .replace(
+                    callPattern,
+                    `__mfe__Registry.for(${JSON.stringify(name)}).injectSheet(__vite__id, __vite__css)`
+                )
+                .replace(
+                    /import\.meta\.hot\.prune\(\(\) => __vite__removeStyle\(__vite__id\)\)/,
+                    ''
+                );
+
+            return { code: transformed, map: null };
+        },
+    };
+}

package/src/vite/plugins/design-system-guard-plugin.ts

@@ -0,0 +1,34 @@
+import path from 'path';
+import type { Plugin } from 'vite';
+import { BuildContext } from '../../core';
+
+const DESIGN_SYSTEM = '@servicetitan/design-system';
+const DESIGN_SYSTEM_CSS = /[\\/]design-system\.css$/;
+
+/*
+ * Errors when a host's own code imports design-system.css while it exposes the design
+ * system as a shared dependency. The CSS already ships in the shared bundle, so a direct
+ * import would load the design system twice. Mirrors the webpack guard in css-rules.ts.
+ */
+export function designSystemGuardPlugin(context: BuildContext): Plugin {
+    const { isExposeSharedDependencies, sharedDependencies } = context.package;
+    const { emitExposedDependencies } = context.build;
+
+    const designSystemInSharedBundle =
+        isExposeSharedDependencies &&
+        !!sharedDependencies[DESIGN_SYSTEM] &&
+        !emitExposedDependencies;
+
+    return {
+        name: 'design-system-guard',
+        enforce: 'pre',
+        resolveId(source, importer) {
+            if (designSystemInSharedBundle && importer && DESIGN_SYSTEM_CSS.test(source)) {
+                const filename = path.parse(importer).name;
+                this.error(
+                    `do not import design-system.css in "${filename}"; it is automatically included as a shared dependency`
+                );
+            }
+        },
+    };
+}

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,111 @@
+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 = resolveTemplatePath(context);
+
+    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();
+            }
+        },
+    };
+}
+
+/*
+ * Resolve the HTML template, mirroring webpack HtmlWebpackPlugin's "auto" default:
+ * an explicit override wins, then a project template (index.ejs, then index.html)
+ * under the package source directory, then the built-in template. Eta renders .ejs
+ * and .html identically, so the extension is a convention, not a syntax switch.
+ */
+function resolveTemplatePath(context: ViteBuildContext): string {
+    const { template } = context.bundlerConfig.pluginOverrides.html ?? {};
+    if (template) {
+        return path.resolve(template);
+    }
+
+    const projectTemplate = ['index.ejs', 'index.html']
+        .map(file => path.resolve(context.package.source, file))
+        .find(file => fs.existsSync(file));
+
+    return projectTemplate ?? path.resolve(__dirname, '../index.html');
+}

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

@@ -0,0 +1,51 @@
+import type { Plugin } from 'vite';
+import { BuildContext, checkResource } from '../../core';
+
+export const THROW_PREFIX = '\0IGNORE_THROW:';
+export const EMPTY_PREFIX = '\0IGNORE_EMPTY:';
+
+/**
+ * Handles optional peer dependencies that are not installed.
+ *
+ * @see {@link file://./../../webpack/configs/plugins/ignore-plugin/ignore-plugin.ts} for the webpack counterpart.
+ *
+ * 'throw' mode: substitutes a virtual module whose body throws "Cannot find module" on
+ *   evaluation. Mirrors webpack's `webpackMissingModule()` semantics. Top-level static
+ *   imports of the resource crash module evaluation, and `try { await import(...) } catch {}`
+ *   (or `try { require(...) } catch {}` in CJS code Rolldown bundles) work as expected.
+ *   This is the default for matched optional peers.
+ *
+ * 'empty' mode: substitutes a virtual module with no exports. Required for top-level
+ *   `import * as X from 'optional'` followed by `X.foo === undefined` detection. Opt in via
+ *   `cli.peerDependenciesMeta["pkg"].fallback = "empty"` in the importer's package.json.
+ */
+export function ignoreModulesPlugin(context: BuildContext): Plugin {
+    const checker = checkResource(context);
+
+    return {
+        name: '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}`;
+            }
+        },
+        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 {};';
+            }
+        },
+    };
+}

package/src/vite/plugins/index.ts

@@ -0,0 +1,16 @@
+export * from './bundle-stat-plugin';
+export * from './chain-source-maps-plugin';
+export * from './clean-plugin';
+export * from './css-injector-plugin';
+export * from './design-system-guard-plugin';
+export * from './dev-server-routing-plugin';
+export * from './externals-plugin';
+export * from './html-plugin';
+export * from './ignore-modules-plugin';
+export * from './istanbul-plugin';
+export * from './magic-comments-plugin';
+export * from './metadata-plugin';
+export * from './moment-locales-plugin';
+export * from './style-urls-plugin';
+export * from './svgr-plugin';
+export * from './virtual-modules-plugin';

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

@@ -0,0 +1,19 @@
+import type { Plugin } from 'vite';
+import { ViteBuildContext } from '../types';
+import { importEsm } from './utils';
+
+export function istanbulPlugin(context: ViteBuildContext): Promise<Plugin> | undefined {
+    if (!context.options.codeCoverage) {
+        return;
+    }
+
+    // vite-plugin-istanbul is ESM-only; load it natively so SWC doesn't rewrite to require.
+    return importEsm<typeof import('vite-plugin-istanbul')>('vite-plugin-istanbul').then(
+        ({ default: istanbul }) =>
+            istanbul({
+                exclude: ['**/node_modules/**', '**/.yalc/**'],
+                requireEnv: false,
+                forceBuildInstrument: true,
+            })
+    );
+}

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

@@ -0,0 +1,105 @@
+import type { ViteBuildContext } from '../../../types';
+import { magicCommentsPlugin } from '../magic-comments-plugin';
+
+describe(`[startup] ${magicCommentsPlugin.name}`, () => {
+    const importPath = './feature';
+    const resolve = jest.fn();
+    const warn = jest.fn();
+    let context: ViteBuildContext;
+    let code: string;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        resolve.mockImplementation(path => ({ id: path }));
+        context = { build: { isProduction: true } } as ViteBuildContext;
+        code = `import('${importPath}');`;
+    });
+
+    const subject = async () => {
+        const plugin = magicCommentsPlugin(context)!;
+        const { chunkFileNames } = (plugin.config as Function)().build.rolldownOptions.output;
+        // Returns chunk name the plugin produces for module imported by `code`
+        await (plugin.transform as { handler: Function }).handler.call({ resolve, warn }, code, '');
+        return chunkFileNames({ facadeModuleId: importPath });
+    };
+
+    function itReturnsDefaultChunkName() {
+        test('returns the default chunk name', async () => {
+            expect(await subject()).toBe('assets/[name]-[hash].js');
+        });
+    }
+
+    itReturnsDefaultChunkName();
+
+    describe('when code contains webpackChunkName comment', () => {
+        const webpackChunkName = 'dashboard';
+
+        beforeEach(
+            () =>
+                (code = code.replace(
+                    'import(',
+                    `import(/* webpackChunkName: '${webpackChunkName}' */`
+                ))
+        );
+
+        test('renames the chunk', async () => {
+            expect(await subject()).toBe(`assets/${webpackChunkName}-[hash].js`);
+        });
+
+        describe('when the import cannot be resolved', () => {
+            beforeEach(() => resolve.mockReturnValue(null));
+
+            itReturnsDefaultChunkName();
+        });
+    });
+
+    describe('when a chunk name is reused for different modules', () => {
+        beforeEach(() => {
+            code = [
+                "import(/* webpackChunkName: 'shared' */ './a')",
+                "import(/* webpackChunkName: 'shared' */ './b')",
+            ].join(';');
+        });
+
+        test('warns that the modules will not be merged', async () => {
+            await subject();
+
+            expect(warn).toHaveBeenCalledWith(expect.stringMatching(/used by multiple modules/));
+        });
+    });
+
+    describe('when the same module is imported twice with one name', () => {
+        beforeEach(() => {
+            code = [
+                `import(/* webpackChunkName: 'dashboard' */ './a')`,
+                `import(/* webpackChunkName: 'dashboard' */ './a')`,
+            ].join(';');
+        });
+
+        test('does not warn', async () => {
+            await subject();
+
+            expect(warn).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('transform filter', () => {
+        const subject = () =>
+            (magicCommentsPlugin(context) as { transform: { filter: unknown } }).transform.filter;
+
+        test('excludes node_modules and requires the magic comment', () => {
+            expect(subject()).toEqual({
+                id: { exclude: /node_modules/ },
+                code: 'webpackChunkName',
+            });
+        });
+    });
+
+    describe('when not a production build', () => {
+        beforeEach(() => (context.build.isProduction = false));
+
+        test('is undefined', () => {
+            expect(magicCommentsPlugin(context)).toBeUndefined();
+        });
+    });
+});

package/src/vite/plugins/magic-comments-plugin/__tests__/parse-magic-comments.test.ts

@@ -0,0 +1,40 @@
+import { parseMagicComments } from '../parse-magic-comments';
+
+describe(`[startup] ${parseMagicComments.name}`, () => {
+    const cases = [
+        // single-quoted comment and import path
+        {
+            code: "import(/* webpackChunkName: 'feature' */ './module');",
+            result: [{ chunkName: 'feature', importPath: './module' }],
+        },
+        // double-quoted comment and import path
+        {
+            code: 'import(/* webpackChunkName: "feature" */ "./module");',
+            result: [{ chunkName: 'feature', importPath: './module' }],
+        },
+        // multiple dynamic imports; the unannotated one is dropped
+        {
+            code: [
+                "import(/* webpackChunkName: 'featureA' */ './moduleA')",
+                "import(/* webpackChunkName: 'featureB' */ './moduleB')",
+                "import('./moduleC')",
+            ].join(';'),
+            result: [
+                { chunkName: 'featureA', importPath: './moduleA' },
+                { chunkName: 'featureB', importPath: './moduleB' },
+            ],
+        },
+        // dynamic import without a magic comment
+        { code: "import('./module');", result: [] },
+        // non-string (computed) import path
+        { code: "import(/* webpackChunkName: 'feature' */ modulePath);", result: [] },
+        // static import
+        { code: "import /* webpackChunkName: 'feature' */ './module';", result: [] },
+    ];
+
+    cases.forEach(({ code, result }) => {
+        test(`with ${code} returns ${JSON.stringify(result)}`, async () => {
+            await expect(parseMagicComments(code)).resolves.toEqual(result);
+        });
+    });
+});

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

@@ -0,0 +1 @@
+export * from './magic-comments-plugin';