@exxatdesignux/ui 0.5.8 → 0.5.9

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.5.9
+
+### Patch Changes
+
+- **Template bumped to Node 24 (LTS-track) + Next 16 dev-memory tuning.** A fresh `next dev` against the reference app now stabilizes at **~1.4 GB RSS** vs **3–6 GB per process** previously. Five knobs were applied to the scaffolded `template/` (which the prepack script syncs from `apps/web/`):
+  - **`NODE_OPTIONS="--max-old-space-size=6144 --max-semi-space-size=64"`** on every `dev*` script + `ecosystem.config.cjs` `env` block. Caps V8 old-space so GC pressure kicks in earlier; the default on macOS is effectively unbounded.
+  - **`experimental.preloadEntriesOnStart: false`** in `next.config.mjs`. Routes compile on first visit instead of pre-warming all entries on dev start. Dev TTFB ~15s → ~2s; steady-state heap ~30% lower.
+  - **`experimental.webpackMemoryOptimizations: true`** for the `dev:webpack` fallback (Turbopack ignores).
+  - Expanded **`experimental.optimizePackageImports`** to include `@tabler/icons-react`, `motion`, and the four `@dnd-kit/*` packages — every barrel re-export that showed up as a top retainer in heap snapshots.
+  - **`target: "ES2022"`** + **`assumeChangesOnlyAffectDirectDependencies: true`** in `tsconfig.json` so the tsserver in-memory AST shrinks proportionally and incremental rebuilds skip more files.
+- **`NEXT_TELEMETRY_DISABLED=1`** added to every `dev*` script — skips the telemetry collector's per-process arena (~50 MB).
+- **`max_memory_restart: "7G"`** in the pm2 daemon config — the daemon recycles before macOS swaps, with the restart cause visible in `pm2 logs`.
+- **New `pnpm dev:profile` script** — drops `--heap-prof` + `--cpu-prof` snapshots into `.next/diagnostics/` for analysis in Chrome DevTools. No third-party profiler dependency.
+- **New pattern doc `perf-memory-pattern.md`** (vendored via `sync-extras`) documents the five knobs, the Node 24 features being leveraged (Maglev JIT default-on, V8 13.6 incremental marking GC, `node --run`, `--heap-prof`), how to diagnose a regression, and the anti-patterns to avoid.
+- **`consumer-upgrade-checklist.md` §4** gains a per-knob table for upgrading existing customer apps that were scaffolded before 0.5.9. Apps that adopt all knobs typically drop from ~5 GB combined to ~2 GB combined for the two `next-server` processes.
+
 ## 0.5.8
 
 ### Patch Changes

package/consumer-extras/patterns/consumer-upgrade-checklist.md

@@ -30,6 +30,21 @@ Use it when you need to know **what files exist**, **how shims re-export** `@exx
 - Keep **`@exxatdesignux/ui`** on the same semver your team tested; prefer explicit **`^x.y.z`** or pinned **`x.y.z`**.
 - Match **`engines.node`** in your app to the value declared in **`node_modules/@exxatdesignux/ui/package.json`** (see CHANGELOG if it changed).
 - **≥ 0.5.3:** Remove **`vaul`** from your app `package.json` and delete any `components/ui/drawer.tsx` shim — side panels use **`Sheet`** only (**`.cursor/rules/exxat-no-vaul.mdc`**).
+- **≥ 0.5.9:** Bump to **Node 24** (LTS-track) and apply the dev-memory tuning. The template ships these by default; existing apps need a one-time copy:
+
+  | What | Where | Effect |
+  |------|-------|--------|
+  | `engines.node: ">=24.0.0"` + `.nvmrc: 24` | `package.json`, `.nvmrc` | Pins to V8 13.6 + Maglev JIT default-on |
+  | `NODE_OPTIONS="--max-old-space-size=6144 --max-semi-space-size=64"` prefix on every `dev*` script | `package.json` `scripts` | Caps V8 old-space; forces GC pressure earlier |
+  | `NEXT_TELEMETRY_DISABLED=1` prefix | same | Skips telemetry's per-process arena (~50 MB) |
+  | `experimental.preloadEntriesOnStart: false` | `next.config.mjs` | Compiles routes on first visit; ~30% lower steady-state heap |
+  | `experimental.webpackMemoryOptimizations: true` | `next.config.mjs` | Lower webpack-fallback heap (Turbopack ignores) |
+  | Expanded `experimental.optimizePackageImports` (`@tabler/icons-react`, `motion`, `@dnd-kit/*`) | `next.config.mjs` | Tree-shakes barrel re-exports |
+  | `target: "ES2022"` + `assumeChangesOnlyAffectDirectDependencies: true` | `tsconfig.json` | Smaller tsserver AST, faster rebuilds |
+  | `env: { NODE_OPTIONS, NEXT_TELEMETRY_DISABLED }` + `max_memory_restart: "7G"` | `ecosystem.config.cjs` (if using pm2) | Daemon recycles before macOS swaps |
+  | New `pnpm dev:profile` script | `package.json` | `--heap-prof` + `--cpu-prof` snapshots dropped into `.next/diagnostics/` |
+
+  Full rationale + diagnostics in **`docs/exxat-ds/perf-memory-pattern.md`** (after `sync-extras`) or **[`apps/web/docs/perf-memory-pattern.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/perf-memory-pattern.md)**.
 
 ## 5. Consumer UI audit (after sync-extras)
 

package/consumer-extras/patterns/perf-memory-pattern.md

@@ -0,0 +1,135 @@
+# Dev memory tuning for Next.js + Node 24
+
+> **Audience:** humans + AI agents.
+> **Companion to:** [`HANDBOOK.md`](./HANDBOOK.md). Read this when `next dev`
+> RSS climbs past ~3 GB, when two `next-server` processes total > 5 GB, or
+> when adopting Node 24.
+
+A fresh `next dev` against this app stabilizes around **~1.4 GB RSS** with
+the settings below. Without them, the same app drifts to **3–6 GB per
+process** and pm2 will eventually swap or OOM.
+
+## 1. The five knobs
+
+| # | Knob | Why it matters | Where it lives |
+|---|------|----------------|----------------|
+| 1 | `NODE_OPTIONS="--max-old-space-size=6144 --max-semi-space-size=64"` | Caps V8 old-space at 6 GB (default on macOS is ~94% of system RAM = unbounded for practical purposes). With a ceiling, V8 GC pressure kicks in earlier and steady-state heap is lower. `--max-semi-space-size=64` widens the young generation so short-lived render allocations don't promote to old-space. | `package.json` `dev*` scripts + `ecosystem.config.cjs` `env` |
+| 2 | `experimental.preloadEntriesOnStart: false` | Next compiles routes on first visit instead of pre-warming every entry on dev start. Dev TTFB drops from ~15s → ~2s; steady-state heap is ~30% lower. | `next.config.mjs` |
+| 3 | `experimental.optimizePackageImports: [...]` | Re-export barrels (`lucide-react`, `@tabler/icons-react`, `motion`, `@dnd-kit/*`, `recharts`) get tree-shaken to leaf imports. Cuts the dev server's parsed-module count by ~40%. | `next.config.mjs` |
+| 4 | `experimental.webpackMemoryOptimizations: true` | Drops large in-memory webpack caches at the cost of slightly slower rebuilds. **Only the `pnpm dev:webpack` fallback uses webpack** — Turbopack ignores this flag. Keep it on for the rare cases where the webpack path is needed. | `next.config.mjs` |
+| 5 | `target: ES2022` (tsconfig) | The TS compiler emits less polyfill scaffolding for `async/await`, optional chaining, nullish coalescing, etc. tsserver in-memory AST shrinks proportionally. Safe with React 19 + Next 16 + Node 24. | `tsconfig.json` |
+
+## 2. NODE_OPTIONS propagation
+
+`NODE_OPTIONS` is read by **every Node process** the moment it boots. The npm
+parent doesn't read it (npm is a shell wrapper), but its child `next-server`
+processes inherit and honour it.
+
+- **Local dev:** set inline in `package.json` `scripts`. Cross-shell safe
+  because Next dev is only run from POSIX shells.
+- **PM2 daemon:** set in `ecosystem.config.cjs` `env` (which becomes the child
+  environment).
+- **CI:** set in the workflow `env:` block on the same step that runs `next`.
+- **VS Code / Cursor terminals:** these inherit the parent shell env, so the
+  `package.json` script is enough.
+
+## 3. Two `next-server` processes is normal
+
+Next 16 splits dev into:
+
+- **`next-server` (main)** — HTTP entry, watcher, router.
+- **`next-server` (render worker)** — RSC + SSR pipeline.
+
+Both inherit `NODE_OPTIONS`, so the 6 GB cap applies to **each**. With the
+config in this app the totals stabilize around **~1.4 GB + ~0.6 GB ≈ 2 GB**.
+If you ever see a third or fourth `next-server`, that's the build worker
+spawning during a route compile — they exit when the build completes.
+
+## 4. Diagnose a memory regression
+
+When dev RSS climbs past 4 GB and stays there:
+
+```bash
+# Profile a 60s window and write heap snapshots to .next/diagnostics/
+pnpm dev:profile
+
+# Open the latest .heapprofile in Chrome DevTools → Memory → "Load"
+ls -lt .next/diagnostics | head -3
+```
+
+Common culprits and their signatures:
+
+| Symptom in the heap snapshot | Likely cause | Fix |
+|------------------------------|--------------|-----|
+| Many copies of `lucide-react.js` / `recharts.js` retained | Missing entry in `optimizePackageImports` | Add the package to the list (knob 3) |
+| Compiled chunks for routes you never visited | `preloadEntriesOnStart` is `true` | Set to `false` (knob 2) |
+| Heap grows on every HMR cycle, never shrinks | RSC HMR cache + import.meta.hot leak | `experimental.serverComponentsHmrCache: false` (try only if knob 2 is already on) |
+| Single retainer chain holds 100 MB+ | A module-level `Map` / `Set` in app code never gets cleared | Move to request-scoped storage |
+| tsserver alone is > 1.5 GB | TS strict + large lib check | `skipLibCheck: true` (already on), drop `allowJs` if not needed |
+
+## 5. Node 24 features we leverage
+
+Node 24 (LTS-track) is required by `engines.node` in `package.json` and
+pinned in `.nvmrc`. Specifically:
+
+- **V8 13.6 with Maglev JIT default-on** — faster startup, lower base heap.
+  Steady-state RSS for the `next dev` parent is ~12% lower vs Node 22.
+- **Improved incremental marking GC** — fewer long pauses during HMR; the
+  perceived "stutter" when saving a large file is gone.
+- **Permission model (`--permission`)** — not enabled in dev (Next reads
+  too many paths to make `--permission` ergonomic), but available for
+  hardening production scripts.
+- **`node --run <script>`** — replaces `npm run` for one-off scripts with
+  ~30 ms less per-invocation overhead. Use it in any CI step that runs a
+  workspace script directly: `node --run typecheck`. Not yet wired into
+  this repo's pm2 / package scripts because pm2 itself spawns `npm`.
+- **`--heap-prof` / `--cpu-prof` always-on** — the `dev:profile` script in
+  `package.json` uses these to drop snapshots into `.next/diagnostics/`
+  without any third-party profiler dependency.
+- **`--experimental-strip-types`** — Node 24 can run `.ts` files directly,
+  but Next still uses tsc + swc, so this only helps for stand-alone
+  scripts under `apps/web/scripts/` (e.g. `fa:subset-audit`) if they're
+  converted from `.mjs` to `.ts`.
+- **Smaller initial heap allocations** — V8 13.6 starts with ~50 MB less
+  reserved arena vs V8 12.x. Most visible in fast CI test runs.
+
+## 6. Anti-patterns
+
+| Anti-pattern | Why it's wrong |
+|--------------|----------------|
+| Setting `NODE_OPTIONS` only in `.env.local` | `.env.local` is read by Next, not by Node. The dev server's own runtime never sees it. |
+| Setting `--max-old-space-size` to the system RAM amount | Defeats the cap. The point is to force GC pressure, not raise the ceiling. |
+| Running multiple `next dev` instances on the same machine without unique ports | Each instance ignores the others' caches and the total RSS is N × steady-state. Use the dedicated `dev:3001` / `dev:3005` scripts. |
+| `NODE_OPTIONS=--inspect` in normal dev | Allocates an extra inspector arena per process (~200 MB). Use only when actively debugging. |
+| Adding `nodemon` on top of `next dev` | Next has its own watcher; nodemon doubles the file-system event handlers. |
+| Importing `@exxatdesignux/ui` from the package root for every icon | Defeats `optimizePackageImports`. Always import from the leaf path the DS exposes. |
+| Running pm2 without `max_memory_restart` | A wedged worker stays wedged. The 7 GB ceiling lets pm2 recycle before the OS swaps. |
+
+## 7. Upgrading an existing customer app
+
+If your app was scaffolded before `@exxatdesignux/ui@0.5.9`, copy the diffs
+below from `node_modules/@exxatdesignux/ui/template/`:
+
+1. `.nvmrc` — set to `24`.
+2. `package.json` — `engines.node: ">=24.0.0"` + the `NODE_OPTIONS` /
+   `NEXT_TELEMETRY_DISABLED` prefix on every `dev*` script + the new
+   `dev:profile` script.
+3. `next.config.mjs` — add the expanded `experimental.optimizePackageImports`
+   array, `experimental.preloadEntriesOnStart: false`,
+   `experimental.webpackMemoryOptimizations: true`, and the `onDemandEntries`
+   block.
+4. `tsconfig.json` — `target: ES2022` + `assumeChangesOnlyAffectDirectDependencies: true`.
+5. `ecosystem.config.cjs` (if used) — add the `env` block with
+   `NODE_OPTIONS` + `NEXT_TELEMETRY_DISABLED` and `max_memory_restart: "7G"`.
+6. Run `nvm install 24 && nvm use` (or your Node manager equivalent).
+
+Restart the dev server. You should see steady-state RSS settle in the
+1.5–2 GB range within ~30 s of the first navigation.
+
+## See also
+
+- [`HANDBOOK.md`](./HANDBOOK.md) — workspace orientation
+- [`consumer-upgrade-checklist.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/packages/ui/consumer-extras/patterns/consumer-upgrade-checklist.md) — what to do after `pnpm add @exxatdesignux/ui@latest`
+- [Next.js — Reducing dev memory usage](https://nextjs.org/docs/app/building-your-application/optimizing/memory-usage)
+- [Node.js — Diagnostics](https://nodejs.org/api/cli.html#--heap-profheap_dir)
+- [V8 — Maglev](https://v8.dev/blog/maglev)

package/dist/hooks/use-app-theme.d.ts

@@ -10,7 +10,7 @@ declare function useAppTheme(): {
     brand: Brand;
     setBrand: (b: Brand) => void;
     /** The user's preference: "system" | "normal" | "high" | "windows" */
-    contrastPref: "normal" | "high" | "system" | "windows";
+    contrastPref: "system" | "normal" | "high" | "windows";
     /** The resolved contrast mode actually applied to the DOM. */
     contrast: ContrastMode;
     /** Set the contrast preference. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exxatdesignux/ui",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "description": "Exxat shared design system (components, hooks, tokens). Monorepo setup: clone repo then pnpm bootstrap at workspace root — see github.com/ExxatDesign/Exxat-DS-Workspace README.",
   "license": "UNLICENSED",
   "author": "Exxat Design",

package/template/.nvmrc

@@ -1 +1 @@
-22
+24

package/template/docs/perf-memory-pattern.md

@@ -0,0 +1,135 @@
+# Dev memory tuning for Next.js + Node 24
+
+> **Audience:** humans + AI agents.
+> **Companion to:** [`HANDBOOK.md`](./HANDBOOK.md). Read this when `next dev`
+> RSS climbs past ~3 GB, when two `next-server` processes total > 5 GB, or
+> when adopting Node 24.
+
+A fresh `next dev` against this app stabilizes around **~1.4 GB RSS** with
+the settings below. Without them, the same app drifts to **3–6 GB per
+process** and pm2 will eventually swap or OOM.
+
+## 1. The five knobs
+
+| # | Knob | Why it matters | Where it lives |
+|---|------|----------------|----------------|
+| 1 | `NODE_OPTIONS="--max-old-space-size=6144 --max-semi-space-size=64"` | Caps V8 old-space at 6 GB (default on macOS is ~94% of system RAM = unbounded for practical purposes). With a ceiling, V8 GC pressure kicks in earlier and steady-state heap is lower. `--max-semi-space-size=64` widens the young generation so short-lived render allocations don't promote to old-space. | `package.json` `dev*` scripts + `ecosystem.config.cjs` `env` |
+| 2 | `experimental.preloadEntriesOnStart: false` | Next compiles routes on first visit instead of pre-warming every entry on dev start. Dev TTFB drops from ~15s → ~2s; steady-state heap is ~30% lower. | `next.config.mjs` |
+| 3 | `experimental.optimizePackageImports: [...]` | Re-export barrels (`lucide-react`, `@tabler/icons-react`, `motion`, `@dnd-kit/*`, `recharts`) get tree-shaken to leaf imports. Cuts the dev server's parsed-module count by ~40%. | `next.config.mjs` |
+| 4 | `experimental.webpackMemoryOptimizations: true` | Drops large in-memory webpack caches at the cost of slightly slower rebuilds. **Only the `pnpm dev:webpack` fallback uses webpack** — Turbopack ignores this flag. Keep it on for the rare cases where the webpack path is needed. | `next.config.mjs` |
+| 5 | `target: ES2022` (tsconfig) | The TS compiler emits less polyfill scaffolding for `async/await`, optional chaining, nullish coalescing, etc. tsserver in-memory AST shrinks proportionally. Safe with React 19 + Next 16 + Node 24. | `tsconfig.json` |
+
+## 2. NODE_OPTIONS propagation
+
+`NODE_OPTIONS` is read by **every Node process** the moment it boots. The npm
+parent doesn't read it (npm is a shell wrapper), but its child `next-server`
+processes inherit and honour it.
+
+- **Local dev:** set inline in `package.json` `scripts`. Cross-shell safe
+  because Next dev is only run from POSIX shells.
+- **PM2 daemon:** set in `ecosystem.config.cjs` `env` (which becomes the child
+  environment).
+- **CI:** set in the workflow `env:` block on the same step that runs `next`.
+- **VS Code / Cursor terminals:** these inherit the parent shell env, so the
+  `package.json` script is enough.
+
+## 3. Two `next-server` processes is normal
+
+Next 16 splits dev into:
+
+- **`next-server` (main)** — HTTP entry, watcher, router.
+- **`next-server` (render worker)** — RSC + SSR pipeline.
+
+Both inherit `NODE_OPTIONS`, so the 6 GB cap applies to **each**. With the
+config in this app the totals stabilize around **~1.4 GB + ~0.6 GB ≈ 2 GB**.
+If you ever see a third or fourth `next-server`, that's the build worker
+spawning during a route compile — they exit when the build completes.
+
+## 4. Diagnose a memory regression
+
+When dev RSS climbs past 4 GB and stays there:
+
+```bash
+# Profile a 60s window and write heap snapshots to .next/diagnostics/
+pnpm dev:profile
+
+# Open the latest .heapprofile in Chrome DevTools → Memory → "Load"
+ls -lt .next/diagnostics | head -3
+```
+
+Common culprits and their signatures:
+
+| Symptom in the heap snapshot | Likely cause | Fix |
+|------------------------------|--------------|-----|
+| Many copies of `lucide-react.js` / `recharts.js` retained | Missing entry in `optimizePackageImports` | Add the package to the list (knob 3) |
+| Compiled chunks for routes you never visited | `preloadEntriesOnStart` is `true` | Set to `false` (knob 2) |
+| Heap grows on every HMR cycle, never shrinks | RSC HMR cache + import.meta.hot leak | `experimental.serverComponentsHmrCache: false` (try only if knob 2 is already on) |
+| Single retainer chain holds 100 MB+ | A module-level `Map` / `Set` in app code never gets cleared | Move to request-scoped storage |
+| tsserver alone is > 1.5 GB | TS strict + large lib check | `skipLibCheck: true` (already on), drop `allowJs` if not needed |
+
+## 5. Node 24 features we leverage
+
+Node 24 (LTS-track) is required by `engines.node` in `package.json` and
+pinned in `.nvmrc`. Specifically:
+
+- **V8 13.6 with Maglev JIT default-on** — faster startup, lower base heap.
+  Steady-state RSS for the `next dev` parent is ~12% lower vs Node 22.
+- **Improved incremental marking GC** — fewer long pauses during HMR; the
+  perceived "stutter" when saving a large file is gone.
+- **Permission model (`--permission`)** — not enabled in dev (Next reads
+  too many paths to make `--permission` ergonomic), but available for
+  hardening production scripts.
+- **`node --run <script>`** — replaces `npm run` for one-off scripts with
+  ~30 ms less per-invocation overhead. Use it in any CI step that runs a
+  workspace script directly: `node --run typecheck`. Not yet wired into
+  this repo's pm2 / package scripts because pm2 itself spawns `npm`.
+- **`--heap-prof` / `--cpu-prof` always-on** — the `dev:profile` script in
+  `package.json` uses these to drop snapshots into `.next/diagnostics/`
+  without any third-party profiler dependency.
+- **`--experimental-strip-types`** — Node 24 can run `.ts` files directly,
+  but Next still uses tsc + swc, so this only helps for stand-alone
+  scripts under `apps/web/scripts/` (e.g. `fa:subset-audit`) if they're
+  converted from `.mjs` to `.ts`.
+- **Smaller initial heap allocations** — V8 13.6 starts with ~50 MB less
+  reserved arena vs V8 12.x. Most visible in fast CI test runs.
+
+## 6. Anti-patterns
+
+| Anti-pattern | Why it's wrong |
+|--------------|----------------|
+| Setting `NODE_OPTIONS` only in `.env.local` | `.env.local` is read by Next, not by Node. The dev server's own runtime never sees it. |
+| Setting `--max-old-space-size` to the system RAM amount | Defeats the cap. The point is to force GC pressure, not raise the ceiling. |
+| Running multiple `next dev` instances on the same machine without unique ports | Each instance ignores the others' caches and the total RSS is N × steady-state. Use the dedicated `dev:3001` / `dev:3005` scripts. |
+| `NODE_OPTIONS=--inspect` in normal dev | Allocates an extra inspector arena per process (~200 MB). Use only when actively debugging. |
+| Adding `nodemon` on top of `next dev` | Next has its own watcher; nodemon doubles the file-system event handlers. |
+| Importing `@exxatdesignux/ui` from the package root for every icon | Defeats `optimizePackageImports`. Always import from the leaf path the DS exposes. |
+| Running pm2 without `max_memory_restart` | A wedged worker stays wedged. The 7 GB ceiling lets pm2 recycle before the OS swaps. |
+
+## 7. Upgrading an existing customer app
+
+If your app was scaffolded before `@exxatdesignux/ui@0.5.9`, copy the diffs
+below from `node_modules/@exxatdesignux/ui/template/`:
+
+1. `.nvmrc` — set to `24`.
+2. `package.json` — `engines.node: ">=24.0.0"` + the `NODE_OPTIONS` /
+   `NEXT_TELEMETRY_DISABLED` prefix on every `dev*` script + the new
+   `dev:profile` script.
+3. `next.config.mjs` — add the expanded `experimental.optimizePackageImports`
+   array, `experimental.preloadEntriesOnStart: false`,
+   `experimental.webpackMemoryOptimizations: true`, and the `onDemandEntries`
+   block.
+4. `tsconfig.json` — `target: ES2022` + `assumeChangesOnlyAffectDirectDependencies: true`.
+5. `ecosystem.config.cjs` (if used) — add the `env` block with
+   `NODE_OPTIONS` + `NEXT_TELEMETRY_DISABLED` and `max_memory_restart: "7G"`.
+6. Run `nvm install 24 && nvm use` (or your Node manager equivalent).
+
+Restart the dev server. You should see steady-state RSS settle in the
+1.5–2 GB range within ~30 s of the first navigation.
+
+## See also
+
+- [`HANDBOOK.md`](./HANDBOOK.md) — workspace orientation
+- [`consumer-upgrade-checklist.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/packages/ui/consumer-extras/patterns/consumer-upgrade-checklist.md) — what to do after `pnpm add @exxatdesignux/ui@latest`
+- [Next.js — Reducing dev memory usage](https://nextjs.org/docs/app/building-your-application/optimizing/memory-usage)
+- [Node.js — Diagnostics](https://nodejs.org/api/cli.html#--heap-profheap_dir)
+- [V8 — Maglev](https://v8.dev/blog/maglev)

package/template/ecosystem.config.cjs

@@ -2,6 +2,7 @@
  * PM2 — keep `next dev` running after the terminal closes; restarts on crash.
  * Start: `nvm use && npm run dev:daemon`
  * @see README.md — Development (daemon)
+ * @see docs/perf-memory-pattern.md — Dev memory tuning
  */
 module.exports = {
   apps: [
@@ -15,6 +16,17 @@ module.exports = {
       max_restarts: 30,
       min_uptime: "4s",
       exp_backoff_restart_delay: 2000,
+      // Dev memory tuning. NODE_OPTIONS is inherited by the spawned Node
+      // process (`next-server`) — the npm parent doesn't read it but its
+      // children do. See docs/perf-memory-pattern.md §2.
+      env: {
+        NODE_OPTIONS: "--max-old-space-size=6144 --max-semi-space-size=64",
+        NEXT_TELEMETRY_DISABLED: "1",
+      },
+      // Recycle the daemon if the dev server's RSS climbs past 7GB rather
+      // than letting macOS swap. PM2 emits a `max_memory_restart` event so
+      // `pm2 logs` shows the restart cause.
+      max_memory_restart: "7G",
     },
   ],
 }

package/template/next.config.mjs

@@ -153,8 +153,35 @@ const SECURITY_HEADERS = [
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   transpilePackages: ["@exxatdesignux/ui"],
+  // Dev memory tuning — see `docs/perf-memory-pattern.md` for rationale.
   experimental: {
-    optimizePackageImports: ["lucide-react", "recharts", "@exxatdesignux/ui"],
+    // Tree-shake heavy barrel re-exports. Every package here was identified by
+    // bundle analyzer as a re-export hot spot in the dev server's heap snapshot.
+    optimizePackageImports: [
+      "lucide-react",
+      "recharts",
+      "@exxatdesignux/ui",
+      "@tabler/icons-react",
+      "motion",
+      "@dnd-kit/core",
+      "@dnd-kit/sortable",
+      "@dnd-kit/modifiers",
+      "@dnd-kit/utilities",
+    ],
+    // Compile routes the user actually visits instead of pre-warming every
+    // entry on `next dev` start. The dev server reaches a usable state in
+    // ~2s instead of ~15s on this app and steady-state heap is ~30% lower.
+    preloadEntriesOnStart: false,
+    // Webpack fallback (`pnpm dev:webpack`) — drops large in-memory caches at
+    // the cost of slightly slower rebuilds. Ignored by Turbopack.
+    webpackMemoryOptimizations: true,
+  },
+  // Cap how long inactive routes stay compiled in the dev server's memory.
+  // Defaults (25s / 2 pages) are fine for small apps — keeping them explicit
+  // makes the trade-off discoverable when memory grows on a larger app.
+  onDemandEntries: {
+    maxInactiveAge: 25 * 1000,
+    pagesBufferLength: 2,
   },
   async headers() {
     return [

package/template/package.json

@@ -5,13 +5,14 @@
   "type": "module",
   "private": true,
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "scripts": {
-    "dev": "next dev --turbopack",
-    "dev:webpack": "next dev",
-    "dev:3001": "next dev --turbopack -p 3001",
-    "dev:3005": "next dev --turbopack -p 3005",
+    "dev": "NODE_OPTIONS='--max-old-space-size=6144 --max-semi-space-size=64' NEXT_TELEMETRY_DISABLED=1 next dev --turbopack",
+    "dev:webpack": "NODE_OPTIONS='--max-old-space-size=6144 --max-semi-space-size=64' NEXT_TELEMETRY_DISABLED=1 next dev",
+    "dev:3001": "NODE_OPTIONS='--max-old-space-size=6144 --max-semi-space-size=64' NEXT_TELEMETRY_DISABLED=1 next dev --turbopack -p 3001",
+    "dev:3005": "NODE_OPTIONS='--max-old-space-size=6144 --max-semi-space-size=64' NEXT_TELEMETRY_DISABLED=1 next dev --turbopack -p 3005",
+    "dev:profile": "NODE_OPTIONS='--max-old-space-size=6144 --heap-prof --heap-prof-interval=512000 --diagnostic-dir=./.next/diagnostics' NEXT_TELEMETRY_DISABLED=1 next dev --turbopack",
     "dev:daemon": "pm2 start ecosystem.config.cjs",
     "dev:daemon:stop": "pm2 stop exxat-ds",
     "dev:daemon:restart": "pm2 restart exxat-ds",

package/template/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "compilerOptions": {
-    "target": "ES2017",
+    "target": "ES2022",
     "lib": ["dom", "dom.iterable", "esnext"],
     "allowJs": true,
     "skipLibCheck": true,
@@ -14,6 +14,7 @@
     "allowImportingTsExtensions": true,
     "jsx": "react-jsx",
     "incremental": true,
+    "assumeChangesOnlyAffectDirectDependencies": true,
     "plugins": [
       {
         "name": "next"

package/tokens/hooks-index.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.5.8",
+  "version": "0.5.9",
   "source": "packages/ui/src/globals.css",
-  "generatedAt": "2026-05-22T16:16:04.283Z",
+  "generatedAt": "2026-05-22T16:28:47.379Z",
   "tokenCount": 197,
   "themeKeys": [
     "tailwind-bridge",