fix-broken-next-symlinks

Broken symlinks occur because Turbopack externalizes packages into .next/node_modules, and production assemblies exclude devDependencies, leaving symlinks pointing to missing targets. This causes CI or production builds to fail when dynamically imported client packages are omitted.

Reproduce the failure locally using the build → assemble-prod.sh → check-next-symlinks.sh sequence, then either add the missing package to the checker allowlist or migrate it from devDependencies to dependencies, and re-run the verification sequence to confirm resolution.

Allowlist a package when it is strictly client-only and should not ship to production, or move it from devDependencies to dependencies when it is required at runtime. The Skill provides decision guidance based on your build → assemble-prod.sh → check-next-symlinks.sh verification workflow.

Turbopack externalizes packages by creating symlinks in .next/node_modules during the build process. In monorepo setups using pnpm, these symlinks can break when production assemblies exclude devDependencies, causing dynamically imported client packages like socket.io-client to point to missing targets.

This workflow specifically targets Next.js applications in monorepo setups where pnpm deploy excludes devDependencies and Turbopack creates externalized symlinks. It applies the build → assemble-prod.sh → check-next-symlinks.sh sequence to diagnose and verify broken .next/node_modules symlinks.

The fix depends on accurately reproducing the production assembly locally using assemble-prod.sh and check-next-symlinks.sh. If a package is incorrectly allowlisted when it should be a runtime dependency, the symlink target will remain missing in production despite passing local checks.