diff --git a/apps/docs/package.json b/apps/docs/package.json index 6ca41d1c268..a1f451235d1 100644 --- a/apps/docs/package.json +++ b/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", diff --git a/apps/sim/next.config.ts b/apps/sim/next.config.ts index 097fc99960d..356e564ae9a 100644 --- a/apps/sim/next.config.ts +++ b/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 diff --git a/apps/sim/package.json b/apps/sim/package.json index f67948673a7..9ceebd08d2f 100644 --- a/apps/sim/package.json +++ b/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", diff --git a/scripts/prune-turbopack-cache.ts b/scripts/prune-turbopack-cache.ts new file mode 100644 index 00000000000..2437a0dd216 --- /dev/null +++ b/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 { + 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) +})