perf(dev): re-enable the Turbopack dev filesystem cache (5.4x faster restarts)

apps/docs/package.json

@@ -4,7 +4,9 @@
   "private": true,
   "license": "Apache-2.0",
   "scripts": {
-    "dev": "next dev --port 3001",
+    "dev": "bun run dev:cache:cap && next dev --port 3001",
+    "dev:cache:cap": "bun run ../../scripts/prune-turbopack-cache.ts",
+    "dev:clean": "rm -rf .next/dev/cache",
     "build": "fumadocs-mdx && NODE_OPTIONS='--max-old-space-size=8192' next build",
     "start": "next start",
     "postinstall": "fumadocs-mdx",

apps/sim/next.config.ts

@@ -218,7 +218,40 @@ const nextConfig: NextConfig = {
     ],
   },
   experimental: {
-    turbopackFileSystemCacheForDev: false,
+    /**
+     * Turbopack's dev filesystem cache stays ON (this is also the Next default
+     * since v16.1). It is what makes a dev-server restart cheap: without it every
+     * restart recompiles the route graph from scratch.
+     *
+     * Measured locally on `/workspace/[workspaceId]/w`, n=3 per cell, restarting
+     * the dev server between each run:
+     *
+     *   cache OFF   31.4s / 30.1s / 31.9s   RSS ~9.0-9.8 GB
+     *   cache ON     5.7s /  6.1s /  5.7s   RSS ~4.8-5.1 GB
+     *
+     * 5.4x faster restarts and ~1.9x less memory. Cold compile with an empty
+     * cache is unchanged (~32s either way) — the cache only pays back on restart.
+     *
+     * This is deliberately NOT the same decision as `turbopackFileSystemCacheForBuild`
+     * below. That one is measured-harmful for `next build`; this one is
+     * measured-beneficial for `next dev`. It was previously `false`, but that was
+     * incidental — it was introduced by a landing-page redesign (#5408) whose
+     * description never mentions Turbopack, caching, or dev performance, and it
+     * is not covered by the #6078 build A/B cited below.
+     *
+     * The cache is unbounded on disk (an abandoned one reached 78 GB here), so
+     * `scripts/prune-turbopack-cache.ts` is chained into every `dev` script to cap it.
+     * A *corrupted* cache can abort Turbopack outright ("Cache corruption
+     * detected: checksum mismatch") rather than falling back — it depends whether
+     * the damaged region is read. `bun run dev:clean` and restart is the fix.
+     *
+     * If you re-measure any of this: `next dev` compiles routes on demand, so
+     * startup time means nothing — time the first request to a route, restart the
+     * server between runs, and stop it with SIGINT. A `kill -9` mid-write makes
+     * Turbopack discard the partially-written cache and rebuild silently, which
+     * reads as "the cache does nothing" and is how this flag stayed wrong.
+     */
+    turbopackFileSystemCacheForDev: true,
     /**
      * Turbopack's persistent build cache (beta) stays off — it is a net loss at
      * this app's size. A controlled A/B on a byte-identical module graph (PR

apps/sim/package.json

@@ -8,9 +8,10 @@
     "node": ">=22.19.0"
   },
   "scripts": {
-    "dev": "next dev --port 3000",
-    "dev:minimal": "SIM_DEV_MINIMAL_REGISTRY=1 next dev --port 3000",
-    "dev:capped": "NODE_OPTIONS='--max-old-space-size=4096' next dev --port 3000",
+    "dev": "bun run dev:cache:cap && next dev --port 3000",
+    "dev:minimal": "bun run dev:cache:cap && SIM_DEV_MINIMAL_REGISTRY=1 next dev --port 3000",
+    "dev:capped": "bun run dev:cache:cap && NODE_OPTIONS='--max-old-space-size=4096' next dev --port 3000",
+    "dev:cache:cap": "bun run ../../scripts/prune-turbopack-cache.ts",
     "dev:clean": "rm -rf .next/dev/cache",
     "dev:webpack": "next dev --webpack",
     "load:workflow": "bun run load:workflow:baseline",

scripts/prune-turbopack-cache.ts

@@ -0,0 +1,114 @@
+#!/usr/bin/env bun
+/**
+ * Caps the size of Turbopack's dev filesystem cache.
+ *
+ * `experimental.turbopackFileSystemCacheForDev` is ON (see `apps/sim/next.config.ts`)
+ * because it makes dev-server restarts 5.4x faster and cuts RSS ~1.9x. The tradeoff
+ * is that the cache is an append-heavy LSM store with no upstream GC: it grows with
+ * every route compiled and every code change, and it is never pruned. An abandoned
+ * cache in this repo reached 78 GB across 1,848 SST files.
+ *
+ * A stale cache is also slower to read back, so an unbounded one eventually erodes
+ * the win it exists to provide. This script drops the whole cache once it crosses a
+ * threshold; Turbopack rebuilds it on the next run (one cold compile, ~32s).
+ *
+ * Also the remedy when Turbopack aborts with `Cache corruption detected:
+ * checksum mismatch` — it does not self-heal from a corrupted cache, so prune
+ * and restart. (An ordinary hard kill does not corrupt it; Turbopack discards a
+ * partial write and rebuilds silently.)
+ *
+ * Runs automatically before every `dev` script. Also invokable directly:
+ *   bun run scripts/prune-turbopack-cache.ts            # prune if over the cap
+ *   bun run scripts/prune-turbopack-cache.ts --force    # always prune
+ *   bun run scripts/prune-turbopack-cache.ts --dry-run  # report only
+ *
+ * Override the cap with `SIM_TURBOPACK_CACHE_MAX_GB` (default 20).
+ *
+ * The cap is a backstop, not routine maintenance. A normal session's cache sits
+ * around 1-2 GB; the 78 GB case was a month of accumulation while the feature was
+ * effectively abandoned. Measured cost of the size walk: ~30ms on a real cache,
+ * ~85ms at 2,000 files — under 2% of a warm restart.
+ *
+ * Safe to run while a dev server is live, which happens if a second server is
+ * started from the same checkout: the running server keeps its in-memory state
+ * and continues serving (verified — no crash, no corruption). It does stop
+ * persisting for the rest of that session, so its *next* start is cold once, then
+ * back to normal. Nothing to clean up.
+ *
+ * Note for anyone benchmarking the cache: stop the dev server with SIGINT, not
+ * `kill -9`. Turbopack discards a partially-written cache and rebuilds silently,
+ * so a hard kill makes a real cache win read as no win at all.
+ */
+import { existsSync, statSync } from 'node:fs'
+import { readdir, rm, stat } from 'node:fs/promises'
+import path from 'node:path'
+
+const DEFAULT_MAX_GB = 20
+const BYTES_PER_GB = 1024 ** 3
+
+/**
+ * Resolved from the working directory, not hardcoded to one app: every Next app
+ * in the monorepo has its own dev cache (`apps/docs` runs `next dev` too and, with
+ * no override, uses the Next default where the cache is on). Each app caps its
+ * own, so one app's dev start never prunes a cache another app is holding open.
+ */
+const CACHE_DIR = path.resolve(process.cwd(), '.next', 'dev', 'cache', 'turbopack')
+
+/** Sums the size of every regular file under `dir`, skipping symlinks. */
+async function directorySize(dir: string): Promise<number> {
+  let total = 0
+  const entries = await readdir(dir, { withFileTypes: true, recursive: true })
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    try {
+      total += (await stat(path.join(entry.parentPath, entry.name))).size
+    } catch {
+      // Turbopack compacts while we walk; a file vanishing mid-scan is expected.
+    }
+  }
+  return total
+}
+
+function parseMaxGb(): number {
+  const raw = process.env.SIM_TURBOPACK_CACHE_MAX_GB
+  if (!raw) return DEFAULT_MAX_GB
+  const parsed = Number(raw)
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    console.warn(
+      `[turbopack-cache] ignoring invalid SIM_TURBOPACK_CACHE_MAX_GB=${raw}, using ${DEFAULT_MAX_GB}`
+    )
+    return DEFAULT_MAX_GB
+  }
+  return parsed
+}
+
+async function main() {
+  const force = process.argv.includes('--force')
+  const dryRun = process.argv.includes('--dry-run')
+
+  if (!existsSync(CACHE_DIR) || !statSync(CACHE_DIR).isDirectory()) return
+
+  const maxGb = parseMaxGb()
+  const bytes = await directorySize(CACHE_DIR)
+  const gb = bytes / BYTES_PER_GB
+  const sizeLabel = `${gb.toFixed(1)} GB`
+
+  if (!force && gb <= maxGb) {
+    if (dryRun) console.log(`[turbopack-cache] ${sizeLabel} (cap ${maxGb} GB) — keeping`)
+    return
+  }
+
+  const reason = force ? 'forced' : `over the ${maxGb} GB cap`
+  if (dryRun) {
+    console.log(`[turbopack-cache] ${sizeLabel} is ${reason} — would prune (dry run)`)
+    return
+  }
+
+  console.log(`[turbopack-cache] ${sizeLabel} is ${reason} — pruning; next start recompiles cold`)
+  await rm(CACHE_DIR, { recursive: true, force: true })
+}
+
+main().catch((error) => {
+  // Never block `next dev` on a cache-maintenance failure.
+  console.warn('[turbopack-cache] prune skipped:', error)
+})