Optimizing dev server startup times for large monorepos

Diagnosing the Monorepo Startup Stall

When a workspace exceeds 500 packages, the dev server initialization frequently hangs during the dependency pre-bundling phase. This manifests as a prolonged vite:deps log trace where the optimizer attempts to resolve transitive dependencies across package boundaries. Understanding how the Vite Module Graph and Dependency Resolution handles workspace symlinks is critical to isolating the bottleneck.

Error Signature

• Symptom: Dev server cold start exceeds 45s in pnpm/yarn workspaces with >500 packages
• CLI Output Pattern: vite:deps Pre-bundling dependencies... (stalls at 80%)
• Log Trace: ESBUILD_ERROR: Failed to resolve entry for package '@internal/ui-lib' with 'module' field

Engineering Steps

1. Capture resolution latency: DEBUG=vite:deps vite dev 2>&1 | grep 'Optimizing dependencies'
2. Identify packages triggering synchronous CJS-to-ESM conversion by filtering for transforming or bundling stalls in the debug stream.
3. Verify symlink integrity across workspace boundaries: ls -la node_modules/@internal

Root Cause: Recursive Graph Traversal & Cache Invalidation

The core issue stems from the bundler treating internal workspace packages as external dependencies. Each cold start forces a full graph traversal, which conflicts with the foundational JavaScript Build Pipeline & Module Resolution Fundamentals that dictate static analysis should precede runtime execution. When optimizeDeps lacks explicit workspace scoping, the resolver falls back to dynamic require() chains, causing esbuild to stall on circular workspace references.

Architectural Breakdown

• Mechanism: Recursive workspace dependency crawling triggers full ESM pre-bundling on every cold start.
• Architectural Flaw: Default optimizer treats monorepo internal packages as external, forcing synchronous resolution of transitive CJS/ESM hybrids.
• Graph Impact: Module graph initialization blocks the HTTP server until the dependency optimizer finishes scanning node_modules/.vite.

Engineering Steps

1. Audit package.json exports vs main field mismatches in internal packages to identify legacy resolution paths.
2. Map node_modules/.vite/deps cache invalidation triggers by comparing file modification timestamps post-restart.
3. Temporarily disable server.fs.strict to bypass symlink guardrails and confirm path resolution bottlenecks.

Exact Configuration & CLI Remediation

Apply a targeted vite.config.ts patch that scopes optimizeDeps.include to internal namespaces while excluding heavy utility packages that should be resolved at runtime. Configure server.fs.allow to explicitly whitelist parent workspace directories. Pair this with an exports-first package manifest to eliminate legacy CommonJS fallback chains and enforce deterministic ESM resolution.

Configuration Patch (vite.config.ts)

import { defineConfig } from 'vite';

export default defineConfig({
  optimizeDeps: {
  include: ['@internal/*'],
  exclude: ['@internal/shared-utils'],
  force: false,
  esbuildOptions: {
  resolveExtensions: ['.ts', '.tsx', '.mjs']
  }
  },
  server: {
  fs: {
  strict: false,
  allow: ['../packages']
  },
  watch: {
  ignored: ['**/node_modules/**', '**/dist/**']
  }
  }
});

CLI Override & Package Manifest Tweak Execute the dev server with explicit cache persistence and reduced verbosity:

vite --host --force=false --logLevel=warn

Update workspace root package.json to enforce modern resolution:

{
 "type": "module",
 "exports": {
 ".": {
 "import": "./dist/index.js",
 "types": "./dist/index.d.ts"
 }
 }
}

Fallback Logic If optimizeDeps.include causes duplicate chunking during HMR, revert to exclude: ['@internal/*'] and rely on Vite’s native ESM pre-bundling fallback. Ensure server.fs.allow points to the absolute monorepo root if relative paths fail in CI environments. If force: false yields stale caches after major dependency upgrades, run rm -rf node_modules/.vite once before restarting.

Verification & Regression Protocol

Validate the fix by measuring cold start latency using time vite dev and confirming the pre-bundle cache hit rate exceeds 95%. Monitor HMR propagation across package boundaries to ensure no regression in update latency. If startup times regress after dependency updates, clear the .vite cache and re-run the diagnostic pipeline to isolate newly introduced resolution conflicts.

Performance Targets

• Primary KPI: Cold start time < 8s (measured via time vite dev)
• Secondary KPI: HMR update latency < 50ms for cross-package imports
• Success Threshold: Pre-bundle cache hit rate > 95% across consecutive restarts

Engineering Steps

1. Benchmark against baseline (45s -> <8s) using hyperfine:

hyperfine --warmup 2 'vite dev --force=false'

2. Automate cache validation in CI pre-merge hooks by asserting node_modules/.vite/_metadata.json exists and contains valid dependency hashes.
3. Cross-verify with vite-plugin-visualizer to ensure no duplicate chunk generation from misconfigured optimizeDeps scopes.