remotion_service/.claude/agents-memory/debug-specialist/2026-03-25-turbopack-hang-vidstack-barrel.md

Turbopack Dev Server Hang — @vidstack/react + Barrel Circular Import

Applies when: Next.js dev server hangs (290%+ CPU, 1GB+ RAM, no HTTP responses), or Turbopack enters infinite recompilation

Three contributing factors found:

1. Barrel self-import in features/project: SubtitleRevisionStep.tsx imports TranscriptionEditor from the barrel @features/project which re-exports SubtitleRevisionStep itself, creating a circular module evaluation chain. Fix: use direct subpath import.

2. FSD violation features->widgets: SubtitleRevisionStep imports TimelinePanel from @widgets/, violating FSD layer direction. Not a direct cause of hang but exacerbates module graph complexity.

3. @vidstack/react internal dynamic imports: The library uses 14+ dynamic import() calls internally. Combined with Turbopack's inability to create shared chunks between async chunks in dev mode (GitHub issue vercel/next.js#85119), this can cause pathological module duplication during HMR.

Reproduction: Issue is intermittent — most reliably triggered when editing files that import from @vidstack/react while the browser has the project wizard page open. Fresh server starts work fine.

Quick fix: Change SubtitleRevisionStep.tsx line 23 from import { TranscriptionEditor } from "@features/project" to import { TranscriptionEditor } from "@features/project/TranscriptionEditor".

Long-term: Consider upgrading to Next.js 16.2+ which includes 200+ Turbopack fixes.