Remix Optimizer

Audit a Remix codebase, report what is slow or fragile and why, agree a plan with the user, then fix it. Order: evidence, approval, edits. Remix 3 runs TypeScript directly, serves unbundled browser modules, and hydrates only explicit clientEntry boundaries; changing those boundaries, frames or data access changes behavior and security, so nothing is edited before approval.

Workflow

1. Scope (quick)

• Find the root (package.json). Record: remix version (3.x current; @remix-run/* 2.x is legacy), Node runtime (3.x requires >=24.3), app/routes.ts, app/router.ts, server.ts, app/assets.ts, database adapter, auth/session storage, client entries, frames, and whether this is Remix 3, legacy Remix v2, or React Router framework mode.
• Run python <skill-dir>/scripts/audit.py <project-root> -- static scan of package.json, remix.json, app/routes.ts, app/router.ts, server.ts, app/assets.ts, controllers, data modules and components for legacy v2 patterns, hydration/asset/config issues, middleware ordering, data and security risks, with file:line evidence. Use --json to post-process.
• Classify the pain: slow document TTFB (actions/DB/frames), slow module graph (unbundled assets), hydration cost, slow mutations (forms/actions), deploy/runtime issues, or security/migration. Ask which hurts if unclear.
• Read references/tooling.md once: what can be measured here (remix doctor, production server, Network panel, Server-Timing, remix test, load tests).

2. Audit

The script finds cheap leads; you find the rest by reading. Read app/routes.ts, app/router.ts, the document shell, the 3-5 controllers/actions the user cares about, app/assets.ts, and any clientEntry/Frame components. Load only what applies:

Measure, never guess. Run the production start command (node --import remix/node-tsx server.ts or the platform adapter) behind the same proxy/CDN, then measure that. Dev mode and a single warm page are not evidence. Record document TTFB, module requests/bytes, hydration count, frame requests, action latency and DB time.

Mark each finding Confirmed (build/server output, network/profiler, code evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save it as REMIX_OPTIMIZATION_REPORT.md in the project root, and show the user. Five-line summary, findings table by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, behavior impact). Group near-duplicates.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- narrow clientEntry boundaries, add fallback to slow frames, prefetch intent links, enable asset minify/fingerprint, fix middleware order, add limits/timeouts, select fewer columns, add missing indexes. Low risk.
2. Structural -- move data into actions/frames, split route-owned regions into frames, batch N+1 queries, adopt streaming for slow regions, move CPU work off the request path, shared session/upload storage for replicas. Name each behavior change.
3. Heavy -- Remix v2 → React Router v7/v8 or a Remix 3 rewrite, database adapter change, auth provider migration, SPA mode, bundler adoption for a very large app. Separately approved. Each step: files touched, expected effect, how to verify, how to roll back.

5. Fix

Only approved items, in small groups. After each: tsc --noEmit, remix doctor, remix test, then start the production server. A break must trace to one change. Do not mix a legacy migration with optimization edits. If a change moves auth/session/upload storage, exposes a new browser-reachable module, or changes a frame's HTML contract, stop and ask.

6. Verify and wrap up

Re-measure the same pages and load: document TTFB, module count/bytes, hydration count, frame TTFB, action latency, LCP/INP/CLS, and DB time. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• Server first, hydrate the smallest boundary. clientEntry is the only browser boundary; never hydrate a page because one button needs state.
• Data loads in actions. Components render synchronously; a route-owned region that needs its own data gets a frame/action, not an async component.
• Explicit updates. State is ordinary JavaScript and handle.update() schedules a render; forgetting it is a UI bug, not a framework optimization.
• No build step means module discipline. Unbundled modules need HTTP/2, preloads, minification and fingerprinting; a very large app may eventually justify a bundler.
• Frames are requests. A blocking frame delays TTFB; a fallback streams, but every frame is another action/DB call. Choose whole-page vs per-region deliberately.
• Middleware order is behavior. Sessions before auth, form parsing before CSRF/method override, compression before responses it should wrap, static before enrichment.
• The asset allowlist is a security boundary. Only files under explicit public/ directories should be browser-reachable.
• Caching is correctness first. Personalized HTML and private files are private/no-store; fingerprinted assets are immutable.
• Remix v2 is EOL. The path forward is React Router v7/v8 (evolution) or Remix 3 (rewrite). Do not present Remix 3 as a drop-in upgrade.
• Docs move. Remix 3 ships its docs in node_modules/remix; read those for the installed version instead of recalling Remix v2 APIs.