@servicetitan/startup 36.4.0 → 37.0.0

package/src/vite/config/__tests__/code-splitting.test.ts

@@ -0,0 +1,34 @@
+import { CHUNK_PATTERNS } from '../../../core';
+import type { ViteBuildContext } from '../../types';
+import { getCodeSplitting } from '../code-splitting';
+
+describe(getCodeSplitting.name, () => {
+    let context: ViteBuildContext;
+
+    beforeEach(() => {
+        context = { build: { isProduction: false } } as unknown as ViteBuildContext;
+    });
+
+    const subject = () => getCodeSplitting(context);
+
+    test('returns undefined', () => {
+        expect(subject()).toBeUndefined();
+    });
+
+    describe('when a production build', () => {
+        beforeEach(() => (context.build.isProduction = true));
+
+        test('splits node_modules into prioritized groups', () => {
+            expect(subject()?.groups).toEqual([
+                { name: 'servicetitan', test: CHUNK_PATTERNS.servicetitan, priority: 30 },
+                { name: 'kendo', test: CHUNK_PATTERNS.kendo, priority: 20 },
+                { name: 'vendor-core', test: CHUNK_PATTERNS['vendor-core'], priority: 15 },
+                { name: 'vendor', test: CHUNK_PATTERNS.vendor, priority: 10 },
+            ]);
+        });
+
+        test('sets a 20 KB minimum chunk size', () => {
+            expect(subject()?.minSize).toBe(20 * 1024);
+        });
+    });
+});

package/src/vite/config/__tests__/create-css-config.test.ts

@@ -0,0 +1,58 @@
+import { bundleConstants } from '../../../core';
+import { createCssConfig } from '../create-css-config';
+
+describe(createCssConfig.name, () => {
+    let isProduction: boolean;
+
+    beforeEach(() => {
+        isProduction = false;
+    });
+
+    const subject = () => createCssConfig(isProduction);
+
+    test('uses camelCase locals convention', () => {
+        expect(subject()).toEqual(
+            expect.objectContaining({
+                modules: expect.objectContaining({
+                    localsConvention: bundleConstants.cssModules.localsConvention,
+                }),
+            })
+        );
+    });
+
+    test('uses development name template', () => {
+        expect(subject()).toEqual(
+            expect.objectContaining({
+                modules: expect.objectContaining({
+                    generateScopedName: bundleConstants.cssModules.classnameTemplate.development,
+                }),
+            })
+        );
+    });
+
+    test('sets less math option', () => {
+        expect(subject()).toEqual(
+            expect.objectContaining({
+                preprocessorOptions: {
+                    less: { math: bundleConstants.less.math },
+                },
+            })
+        );
+    });
+
+    describe('when production', () => {
+        beforeEach(() => {
+            isProduction = true;
+        });
+
+        test('uses production name template', () => {
+            expect(subject()).toEqual(
+                expect.objectContaining({
+                    modules: expect.objectContaining({
+                        generateScopedName: bundleConstants.cssModules.classnameTemplate.production,
+                    }),
+                })
+            );
+        });
+    });
+});

package/src/vite/config/__tests__/create-filtering-logger.test.ts

@@ -0,0 +1,51 @@
+import { createLogger, Logger } from 'vite';
+import { createFilteringLogger } from '../create-filtering-logger';
+
+jest.mock('vite', () => ({ createLogger: jest.fn() }));
+
+describe(createFilteringLogger.name, () => {
+    let spies: Record<'warn' | 'warnOnce', jest.Mock>;
+
+    beforeEach(() => {
+        spies = { warn: jest.fn(), warnOnce: jest.fn() };
+        jest.mocked(createLogger).mockReturnValue({ ...spies } as unknown as Logger);
+    });
+
+    describe.each(['warn', 'warnOnce'] as ('warn' | 'warnOnce')[])('%s', method => {
+        let message: string;
+
+        beforeEach(() => (message = 'some message'));
+
+        const subject = () => (createFilteringLogger()[method] as Function)(message);
+
+        test('passes message through', () => {
+            subject();
+
+            expect(spies[method]).toHaveBeenCalled();
+        });
+
+        function itSuppressesMessage() {
+            test('suppresses message', () => {
+                subject();
+
+                expect(spies[method]).not.toHaveBeenCalled();
+            });
+        }
+        describe('when message is shared .js asset warning', () => {
+            beforeEach(() => {
+                message =
+                    '<script src="./shared/shared.abc.bundle.js"> in "/index.html" can\'t be bundled without type="module" attribute';
+            });
+
+            itSuppressesMessage();
+        });
+
+        describe('when message is shared .css asset warning', () => {
+            beforeEach(() => {
+                message = "./shared/anvil2.abc.bundle.css doesn't exist at build time";
+            });
+
+            itSuppressesMessage();
+        });
+    });
+});

package/src/vite/config/__tests__/create-vite-build-context.test.ts

@@ -1,10 +1,13 @@
-import type { BuildContext } from '../../../core';
+import { type BuildContext } from '../../../core';
 import type { VitePackageJsonOverride } from '../../../utils/get-configuration';
 import { createViteBuildContext } from '../create-vite-build-context';
 import type { ViteConfigFileOverride } from '../define-config';
 
 describe(createViteBuildContext.name, () => {
-    const context = { build: { name: 'test' } } as BuildContext;
+    const context = {
+        build: { name: 'test' },
+        package: { destination: 'dist' },
+    } as BuildContext;
 
     let pkgJsonConfig: VitePackageJsonOverride;
     let fileConfig: ViteConfigFileOverride;

package/src/vite/config/__tests__/create-vite-config.test.ts

@@ -1,14 +1,15 @@
-import { createBuildContext } from '../../../core';
+import { createBuildContext, resolveOutputPath, resolveOutputRoot } from '../../../core';
 import { getViteConfiguration } from '../../../utils';
 import { createBaseConfig } from '../base-config';
 import { createViteBuildContext } from '../create-vite-build-context';
 import { createViteConfig } from '../create-vite-config';
+import { getWarmupClientFiles } from '../get-warmup-client-files';
 import { loadConfigFile } from '../load-config-file';
 import { mergeViteConfigs } from '../merge-vite-configs';
 
 jest.mock('../../../core', () => ({
+    ...jest.requireActual('../../../core'),
     createBuildContext: jest.fn(),
-    stringifyConfig: jest.fn(),
 }));
 jest.mock('../../../utils', () => ({
     getViteConfiguration: jest.fn(),
@@ -26,25 +27,36 @@ jest.mock('../load-config-file', () => ({
 jest.mock('../merge-vite-configs', () => ({
     mergeViteConfigs: jest.fn(),
 }));
+jest.mock('../get-warmup-client-files', () => ({
+    getWarmupClientFiles: jest.fn(),
+}));
 
 describe(createViteConfig.name, () => {
     const options = { name: 'test', isProduction: false };
-    const mockPkgConfig: any = { omitDefault: ['from-pkg'] };
-    const mockFileConfig: any = { omitDefault: ['from-file'] };
-    const mockViteContext: any = { bundlerConfig: {} };
+    const warmupFiles = ['dist/**/*.js', '!dist/bundle/**'];
     const mockBaseConfig: any = { root: '/' };
     const mockFinalConfig: any = { server: { port: 3000 } };
 
     let mockContext: any;
+    let mockPackageJsonConfig: any;
+    let mockFileConfig: any;
+    let mockViteBuildContext: any;
 
     beforeEach(() => {
-        mockContext = { build: {} };
+        jest.clearAllMocks();
+
+        mockContext = { build: {}, package: { destination: 'dist' } };
+        mockPackageJsonConfig = { omitDefault: ['from-pkg'] };
+        mockFileConfig = { omitDefault: ['from-file'] };
+        mockViteBuildContext = { ...mockContext, bundlerConfig: {} };
+
         jest.mocked(createBuildContext).mockReturnValue(mockContext);
-        jest.mocked(getViteConfiguration).mockReturnValue(mockPkgConfig);
+        jest.mocked(getViteConfiguration).mockReturnValue(mockPackageJsonConfig);
         jest.mocked(loadConfigFile).mockResolvedValue(mockFileConfig);
-        jest.mocked(createViteBuildContext).mockReturnValue(mockViteContext);
+        jest.mocked(createViteBuildContext).mockReturnValue(mockViteBuildContext);
         jest.mocked(createBaseConfig).mockReturnValue(mockBaseConfig);
         jest.mocked(mergeViteConfigs).mockReturnValue({ ...mockFinalConfig });
+        jest.mocked(getWarmupClientFiles).mockReturnValue(warmupFiles);
     });
 
     const subject = () => createViteConfig(options);
@@ -71,8 +83,8 @@ describe(createViteConfig.name, () => {
         await subject();
 
         expect(createViteBuildContext).toHaveBeenCalledWith(
-            mockContext,
-            mockPkgConfig,
+            expect.objectContaining(mockContext),
+            mockPackageJsonConfig,
             mockFileConfig
         );
     });
@@ -80,7 +92,7 @@ describe(createViteConfig.name, () => {
     test('creates base config from vite context', async () => {
         await subject();
 
-        expect(createBaseConfig).toHaveBeenCalledWith(mockViteContext);
+        expect(createBaseConfig).toHaveBeenCalledWith(mockViteBuildContext);
     });
 
     test('merges base, package.json, and file configs', async () => {
@@ -88,13 +100,79 @@ describe(createViteConfig.name, () => {
 
         expect(mergeViteConfigs).toHaveBeenCalledWith(
             mockBaseConfig,
-            mockPkgConfig,
+            mockPackageJsonConfig,
             mockFileConfig
         );
     });
 
     test('returns merged config', async () => {
-        expect(await subject()).toEqual(expect.objectContaining(mockFinalConfig));
+        expect(await subject()).toEqual(
+            expect.objectContaining({
+                server: expect.objectContaining(mockFinalConfig.server),
+            })
+        );
+    });
+
+    test('resolves build.outDir from the configured outDir', async () => {
+        expect((await subject()).build?.outDir).toBe(resolveOutputPath(mockContext, undefined));
+    });
+
+    test('sets warmup.clientFiles for the dev server', async () => {
+        expect((await subject()).server?.warmup?.clientFiles).toBe(warmupFiles);
+    });
+
+    test('warms the resolved output root', async () => {
+        await subject();
+
+        expect(getWarmupClientFiles).toHaveBeenCalledWith(
+            mockViteBuildContext,
+            resolveOutputRoot(mockContext, undefined)
+        );
+    });
+
+    describe('when consumer config sets warmup', () => {
+        beforeEach(() =>
+            jest.mocked(mergeViteConfigs).mockReturnValue({
+                server: { warmup: { clientFiles: ['custom/**'], ssrFiles: ['ssr/**'] } },
+            })
+        );
+
+        test('consumer clientFiles take precedence', async () => {
+            expect((await subject()).server?.warmup?.clientFiles).toEqual(['custom/**']);
+        });
+
+        test('preserves other consumer warmup options', async () => {
+            expect((await subject()).server?.warmup?.ssrFiles).toEqual(['ssr/**']);
+        });
+    });
+
+    describe('when the merged config sets a custom outDir', () => {
+        const outDir = '/custom';
+
+        beforeEach(() =>
+            jest.mocked(mergeViteConfigs).mockReturnValue({ ...mockFinalConfig, build: { outDir } })
+        );
+
+        test('resolves build.outDir from the custom outDir', async () => {
+            expect((await subject()).build?.outDir).toBe(resolveOutputPath(mockContext, outDir));
+        });
+
+        test('warms the custom output root', async () => {
+            await subject();
+
+            expect(getWarmupClientFiles).toHaveBeenCalledWith(
+                mockViteBuildContext,
+                resolveOutputRoot(mockContext, outDir)
+            );
+        });
+    });
+
+    describe('when production', () => {
+        beforeEach(() => (mockContext.build.isProduction = true));
+
+        test('skips warmup', async () => {
+            expect((await subject()).server?.warmup).toBeUndefined();
+        });
     });
 
     describe('when build is light', () => {

package/src/vite/config/__tests__/get-warmup-client-files.test.ts

@@ -0,0 +1,20 @@
+import path from 'path';
+import type { ViteBuildContext } from '../../types';
+import { getWarmupClientFiles } from '../get-warmup-client-files';
+
+describe(getWarmupClientFiles.name, () => {
+    const destination = 'dist';
+    let context: ViteBuildContext;
+    let outputRoot: string;
+
+    beforeEach(() => {
+        context = { build: {}, package: { destination } } as unknown as ViteBuildContext;
+        outputRoot = path.join(process.cwd(), destination, 'bundle');
+    });
+
+    const subject = () => getWarmupClientFiles(context, outputRoot);
+
+    test('returns compiled output, excluding the bundle output', () => {
+        expect(subject()).toEqual([`${destination}/**/*.js`, `!${destination}/bundle/**`]);
+    });
+});

package/src/vite/config/asset-file-names.ts

@@ -0,0 +1,20 @@
+import {
+    FONT_EXTENSIONS,
+    IMAGE_EXTENSIONS,
+    SVG_EXTENSIONS,
+    createExtensionRegExp,
+} from '../../core';
+
+const FONT = createExtensionRegExp(FONT_EXTENSIONS);
+const IMAGE = createExtensionRegExp([...IMAGE_EXTENSIONS, ...SVG_EXTENSIONS]);
+
+export function assetFileNames(asset: { names: string[] }): string {
+    const name = asset.names[0] ?? '';
+    if (FONT.test(name)) {
+        return 'fonts/[name]-[hash][extname]';
+    }
+    if (IMAGE.test(name)) {
+        return 'images/[name]-[hash][extname]';
+    }
+    return 'assets/[name]-[hash][extname]';
+}

package/src/vite/config/base-config.ts

@@ -6,21 +6,32 @@ import {
     defineWebComponentName,
     getBundleType,
     getCdnPath,
-    getOutputPath,
+    getProcessEnv,
 } from '../../core';
 import { omit } from '../../utils';
 import {
+    bundleStatPlugin,
+    chainSourceMapsPlugin,
+    cleanPlugin,
     cssInjectorPlugin,
+    designSystemGuardPlugin,
     devServerRoutingPlugin,
     externalsPlugin,
     htmlPlugin,
     ignoreModulesPlugin,
+    istanbulPlugin,
+    magicCommentsPlugin,
     metadataPlugin,
+    momentLocalesPlugin,
     styleUrlsPlugin,
     svgrPlugin,
     virtualModulesPlugin,
 } from '../plugins';
 import { ViteBuildContext } from '../types';
+import { assetFileNames } from './asset-file-names';
+import { getCodeSplitting } from './code-splitting';
+import { createCssConfig } from './create-css-config';
+import { createFilteringLogger } from './create-filtering-logger';
 
 function importMetaRemap(
     ...definitions: (Record<string, string> | undefined)[]
@@ -39,16 +50,22 @@ function importMetaRemap(
 }
 
 function createPlugins(context: ViteBuildContext) {
-    const entries: [string, Plugin[] | Plugin | undefined][] = [
-        ['html', htmlPlugin(context)],
-        ['svgr', svgrPlugin(context)],
-        ['externals', externalsPlugin(context)],
-        ['virtualModules', virtualModulesPlugin(context)],
+    const entries: [string, Plugin[] | Plugin | Promise<Plugin> | undefined][] = [
+        ['bundleStat', bundleStatPlugin(context)],
+        ['clean', cleanPlugin(context)],
         ['cssInjector', cssInjectorPlugin(context)],
-        ['styleUrls', styleUrlsPlugin(context)],
-        ['metadata', metadataPlugin(context)],
+        ['designSystemGuard', designSystemGuardPlugin(context)],
         ['devServerRouting', devServerRoutingPlugin(context)],
+        ['externals', externalsPlugin(context)],
+        ['html', htmlPlugin(context)],
         ['ignoreModules', ignoreModulesPlugin(context)],
+        ['istanbul', istanbulPlugin(context)],
+        ['magicComments', magicCommentsPlugin(context)],
+        ['metadata', metadataPlugin(context)],
+        ['momentLocales', momentLocalesPlugin(context)],
+        ['styleUrls', styleUrlsPlugin(context)],
+        ['svgr', svgrPlugin(context)],
+        ['virtualModules', virtualModulesPlugin(context)],
     ];
 
     return entries
@@ -65,47 +82,33 @@ export function createBaseConfig(context: ViteBuildContext): InlineConfig {
 
     let config: InlineConfig = {
         cacheDir: `node_modules/.vite/${getBundleType(context) ?? 'host'}`,
-        server: {
-            port: context.bundlerConfig.port ?? (isWebComponent ? 8888 : 8080),
-            warmup: {
-                // Pre-warms compiled files to avoid multiple page reloads at dev session start
-                clientFiles: [`${context.package.destination}/**/*.js`],
-            },
-        },
+        customLogger: createFilteringLogger(),
+        server: { port: context.bundlerConfig.port ?? (isWebComponent ? 8888 : 8080) },
         mode: isProduction ? bundleConstants.mode.production : bundleConstants.mode.development,
         configFile: false,
         oxc: { legalComments: 'none' },
         base: getCdnPath(context) || './', // eslint-disable-line @typescript-eslint/prefer-nullish-coalescing
-        css: {
-            modules: {
-                localsConvention: bundleConstants.cssModules.localsConvention,
-                generateScopedName: isProduction
-                    ? bundleConstants.cssModules.classnameTemplate.production
-                    : bundleConstants.cssModules.classnameTemplate.development,
-            },
-            preprocessorOptions: {
-                less: { math: bundleConstants.less.math },
-            },
-        },
+        css: createCssConfig(isProduction),
         build: {
             /*
              * MFEs render inside shadow DOM — lazy CSS chunks would inject into document.head,
              * leaking styles into the host. Bundling all CSS into one file avoids this.
              */
             cssCodeSplit: !isWebComponent,
-            /*
-             * MFE bundle dirs (full/light/headless) are safe to clean — no shared deps inside.
-             * Host outDir (dist/bundle/) contains shared/, so cleaning would delete shared deps.
-             */
-            emptyOutDir: isWebComponent,
-            outDir: getOutputPath(context),
             sourcemap: true,
+            rolldownOptions: {
+                output: { assetFileNames, codeSplitting: getCodeSplitting(context) },
+                plugins: [chainSourceMapsPlugin()],
+            },
+        },
+        define: {
+            ...importMetaRemap(
+                defineExposedDependencies(context),
+                defineExposedInstanceDependencies(context),
+                defineWebComponentName(context)
+            ),
+            ...(getProcessEnv(context) ?? {}),
         },
-        define: importMetaRemap(
-            defineExposedDependencies(context),
-            defineExposedInstanceDependencies(context),
-            defineWebComponentName(context)
-        ),
         optimizeDeps: {
             include: ['@servicetitan/startup-utils'],
             /*
@@ -133,5 +136,10 @@ export function createBaseConfig(context: ViteBuildContext): InlineConfig {
         config.build = { ...config.build, cssMinify: !!context.bundlerConfig.minify.css };
     }
 
+    // Minified output can't be mapped back to source, so skip it when instrumenting.
+    if (context.options.codeCoverage) {
+        config.build = { ...config.build, minify: false };
+    }
+
     return config;
 }

package/src/vite/config/code-splitting.ts

@@ -0,0 +1,23 @@
+import type { CodeSplittingGroup, CodeSplittingOptions } from 'rolldown';
+import { CHUNK_PATTERNS } from '../../core';
+import { ViteBuildContext } from '../types';
+
+/*
+ * Rolldown matches higher-priority groups first, so the specific @servicetitan and
+ * Kendo groups claim their modules before the general vendor groups can. Code outside
+ * node_modules matches no group, so it stays in the entry chunk.
+ */
+const VENDOR_GROUPS: CodeSplittingGroup[] = [
+    { name: 'servicetitan', test: CHUNK_PATTERNS.servicetitan, priority: 30 },
+    { name: 'kendo', test: CHUNK_PATTERNS.kendo, priority: 20 },
+    { name: 'vendor-core', test: CHUNK_PATTERNS['vendor-core'], priority: 15 },
+    { name: 'vendor', test: CHUNK_PATTERNS.vendor, priority: 10 },
+];
+
+export function getCodeSplitting(context: ViteBuildContext): CodeSplittingOptions | undefined {
+    if (!context.build.isProduction) {
+        return undefined;
+    }
+
+    return { groups: VENDOR_GROUPS, minSize: 20 * 1024 };
+}

package/src/vite/config/create-css-config.ts

@@ -0,0 +1,16 @@
+import type { CSSOptions } from 'vite';
+import { bundleConstants } from '../../core';
+
+export function createCssConfig(isProduction: boolean): CSSOptions {
+    return {
+        modules: {
+            localsConvention: bundleConstants.cssModules.localsConvention,
+            generateScopedName: isProduction
+                ? bundleConstants.cssModules.classnameTemplate.production
+                : bundleConstants.cssModules.classnameTemplate.development,
+        },
+        preprocessorOptions: {
+            less: { math: bundleConstants.less.math },
+        },
+    };
+}

package/src/vite/config/create-filtering-logger.ts

@@ -0,0 +1,34 @@
+import { createLogger, type Logger } from 'vite';
+
+/*
+ * Expected warnings when a host's HTML references the shared-bundle assets created by
+ * separate "exposed dependencies" build. Matched on ./shared/ so a genuinely missing
+ * app asset still warns.
+ */
+const SHARED_ASSET_WARNINGS = [
+    /<script src="\.\/shared\/[^"]+"> in "[^"]*" can't be bundled without type="module"/,
+    /\.\/shared\/\S+ doesn't exist at build time/,
+];
+
+/*
+ * Wraps Vite's logger to drop the shared-asset HTML warnings. Everything else passes through.
+ */
+export function createFilteringLogger(): Logger {
+    const logger = createLogger();
+    const { warn, warnOnce } = logger;
+    const isSuppressed = (message: string) =>
+        SHARED_ASSET_WARNINGS.some(pattern => pattern.test(message));
+
+    logger.warn = (message, options) => {
+        if (!isSuppressed(message)) {
+            warn.call(logger, message, options);
+        }
+    };
+    logger.warnOnce = (message, options) => {
+        if (!isSuppressed(message)) {
+            warnOnce.call(logger, message, options);
+        }
+    };
+
+    return logger;
+}

package/src/vite/config/create-vite-build-context.ts

@@ -1,6 +1,7 @@
+import { BuildContext } from '../../core';
 import { VitePackageJsonOverride } from '../../utils';
 import { ViteBuildContext } from '../types';
-import { BuildContext, ViteConfigFileOverride } from './define-config';
+import { ViteConfigFileOverride } from './define-config';
 
 function createBundlerConfig(
     packageJsonConfig: VitePackageJsonOverride,
@@ -38,8 +39,5 @@ export function createViteBuildContext(
     pkgJsonConfig: VitePackageJsonOverride,
     fileConfig: ViteConfigFileOverride
 ): ViteBuildContext {
-    return {
-        ...context,
-        bundlerConfig: createBundlerConfig(pkgJsonConfig, fileConfig),
-    };
+    return { ...context, bundlerConfig: createBundlerConfig(pkgJsonConfig, fileConfig) };
 }

package/src/vite/config/create-vite-config.ts

@@ -1,7 +1,14 @@
-import { BuildContextOptions, createBuildContext, stringifyConfig } from '../../core';
+import {
+    BuildContextOptions,
+    createBuildContext,
+    resolveOutputPath,
+    resolveOutputRoot,
+    stringifyConfig,
+} from '../../core';
 import { getViteConfiguration, log } from '../../utils';
 import { createBaseConfig } from './base-config';
 import { createViteBuildContext } from './create-vite-build-context';
+import { getWarmupClientFiles } from './get-warmup-client-files';
 import { loadConfigFile } from './load-config-file';
 import { mergeViteConfigs } from './merge-vite-configs';
 
@@ -12,18 +19,16 @@ export async function createViteConfig(options: BuildContextOptions) {
     const viteContext = createViteBuildContext(context, packageJsonConfig, fileConfig);
     const baseConfig = createBaseConfig(viteContext);
     const finalConfig = mergeViteConfigs(baseConfig, packageJsonConfig, fileConfig);
+    const outputRoot = resolveOutputRoot(context, finalConfig.build?.outDir);
 
-    /*
-     * Background dev servers (light/headless) must use a random port to avoid
-     * conflicting with the full bundle's user-configured port.
-     */
-    if (context.build.light || context.build.headless) {
-        finalConfig.server = { ...finalConfig.server, port: 0 };
-    } else if (!context.build.emitExposedDependencies) {
-        finalConfig.server = {
-            ...finalConfig.server,
-            port: Number(process.env.PORT) || finalConfig.server?.port,
-        };
+    // Resolve the output path: web components force the default, hosts honor a configured path.
+    finalConfig.build = {
+        ...finalConfig.build,
+        outDir: resolveOutputPath(context, finalConfig.build?.outDir),
+    };
+
+    if (!context.build.isProduction) {
+        finalConfig.server = createDevServerConfig(viteContext, finalConfig, outputRoot);
     }
 
     /* istanbul ignore next: debug only */
@@ -31,3 +36,31 @@ export async function createViteConfig(options: BuildContextOptions) {
 
     return finalConfig;
 }
+
+function createDevServerConfig(
+    viteContext: ReturnType<typeof createViteBuildContext>,
+    finalConfig: ReturnType<typeof mergeViteConfigs>,
+    outputRoot: string
+) {
+    const { light, headless, emitExposedDependencies } = viteContext.build;
+
+    const server = {
+        ...finalConfig.server,
+        warmup: {
+            clientFiles: getWarmupClientFiles(viteContext, outputRoot),
+            ...finalConfig.server?.warmup,
+        },
+    };
+
+    /*
+     * Background dev servers (light/headless) must use a random port to avoid
+     * conflicting with the full bundle's user-configured port.
+     */
+    if (light || headless) {
+        server.port = 0;
+    } else if (!emitExposedDependencies) {
+        server.port = Number(process.env.PORT) || finalConfig.server?.port;
+    }
+
+    return server;
+}