Next.js Turbopack Linked Package Reload Fix

The Problem

If you are working in a monorepo and Turbopack stops noticing changes from a linked UI package, you lose time fast. I have seen this on shared design-system packages, internal SDKs, and workspace utilities where the app itself hot reloads fine but edits inside packages/ui or packages/utils do nothing until a restart.

That got more interesting with Next.js 16.2.4 because the release notes included a specific Turbopack fix for filesystem watcher configuration not applying follow_symlinks(false). That is exactly the kind of bug that shows up as "my linked package is stale" when the real issue is the watcher graph.

The release note matters because it changes the first question I ask. Before I start rewriting a workspace setup, I want to know whether the app is simply on the wrong patch release.

If you have been debugging other App Router oddities recently, my async params TypeError write-up is another reminder that patch releases matter more in Next.js 16 than people like to admit.

Why It Happens

There are usually two layers involved:

1. The watcher misses changes from symlinked packages

That is the part 16.2.4 addressed directly. If your workspace uses symlinks under the hood, Turbopack can end up watching the wrong boundary or not refreshing the right dependency edges after a file changes.

2. The package is not configured to be transpiled by Next.js

Even after the watcher behaves, a local package still needs to be part of the app's compilation pipeline. The official transpilePackages docs exist for exactly this reason.

If a local package ships raw TypeScript, JSX, or modern syntax that the app expects Next.js to handle, leaving it out of transpilePackages produces a setup that feels randomly broken. Sometimes it compiles. Sometimes it reloads badly. Sometimes it fails only in one app inside the monorepo.

The Fix

The path I trust is simple.

1. Upgrade the app to at least 16.2.4

If you are below that patch, do that first. This is one of those cases where the changelog is not optional reading.

2. Declare workspace packages explicitly

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  transpilePackages: ['@qasim/ui', '@qasim/utils'],
}

export default nextConfig

That tells Next.js to treat those packages as first-class code, not as opaque external dependencies.

3. Import source consistently

I try to avoid half-built package flows where one app imports src/ directly while another imports prebuilt dist/ output. Pick one model and keep it boring. In most monorepos, importing the workspace package and letting Next.js transpile it is the least fragile route during development.

4. Check the package exports

I have seen reload issues that looked like Turbopack bugs but were actually export-map mistakes:

{
  "name": "@qasim/ui",
  "version": "0.0.1",
  "exports": {
    ".": "./src/index.ts"
  }
}

That works fine if the app is prepared to transpile the package. It is a mess if the package expects a prebuilt output and the app assumes otherwise. Make sure your package contract matches your app setup.

5. Restart once after changing package boundaries

I do not like "just restart it" as advice, but after changing watcher-sensitive config or package export behavior, one clean restart is still worth doing. What I do not accept is having to restart all day long because the workspace graph was never wired correctly.

What I Check Before Blaming Turbopack

My short list is:

• current Next.js version
• transpilePackages coverage
• workspace symlink model
• package exports and main fields
• whether the package ships source or build artifacts

If all of that is sane and reload is still broken, then I start treating it as a framework issue instead of a repo issue.

The Real Lesson

Turbopack is fast when the graph is clear. Linked packages blur that graph unless you tell Next.js exactly what is local, what should be transpiled, and what version of the watcher you are actually running.

That is why I read patch notes before I start inventing webpack-era workarounds.

For the official references, I would start with the Next.js 16.2.4 release notes and the transpilePackages docs. They are enough to keep most monorepo reload bugs from turning into a week of guesswork.

If your monorepo still needs manual restarts every hour, I can clean up the build graph and the package boundaries properly. Details are on my services page, and you can browse my other Next.js fixes while you are here.