Docs: how to enable turbopack's polling feature for the file watcher?

[kayhadrin]

What is the documentation issue?

Based on #69684 / #68255, I believe that the Turbopack incremental builder should be able to detect file changes in Docker containers + WSL2.

However, I couldn't find any doc explaining how to actually use it. :-(

Is it ready for public use?

Is there any context that might help us understand?

I'm using next.js in Docker + WSL2 and tried to use next dev --turbopack but noticed that it won't detect source file changes unless I remove the --turbopack option.
See issue #68255 for more context about this particular issue when watching files in this scenario.

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/app/api-reference/turbopack#module-resolution

[icyJoseph]

Hi,

I'll forward this to the reviewer involved, because looking at the PR description, this looks like a community effort that we might have forgotten to document.

The normal file watcher doesn't work inside a docker container, the workaround is to enable a polling file watcher, which was supported in webpack but not turbopack so far.

Normally the file watcher is active in dev mode.

You can pass a polling interval from the next.config.ts or js, file:

const config = {
  watchOptions: {
    pollIntervalMs: 1000, // some sensible number
  },
};

export default config;

[kayhadrin]

Thanks for the quick reply @icyJoseph!
I've tried adding the suggested watchOptions config but it causes new watch errors to appear:

ubuntu@510f15ec1d1b:~/app$ pnpm next dev --turbopack

> @kayhadrin/threejs-demo@0.0.1 dev /home/ubuntu/app
> next dev --turbopack

   ▲ Next.js 15.3.3 (Turbopack)
   - Local:        http://localhost:3000
   - Network:      http://172.17.0.3:3000
   - Environments: .env.local

 ✓ Starting...
 ✓ Ready in 22s
 ○ Compiling / ...
watch error (["/home/ubuntu/app/node_modules/@opentelemetry"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" }) 
watch error (["/home/ubuntu/app/node_modules/@swc"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" }) 
watch error (["/home/ubuntu/app/.config"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" }) 
watch error (["/home/ubuntu/app/.next-internal"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" }) 
watch error (["/home/ubuntu/app/.next-internal/server"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" }) 
watch error (["/home/ubuntu/app/.next-internal/server/app"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" }) 
watch error (["/home/ubuntu/app/.next-internal/server/app/page"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" }) 
 ✓ Compiled / in 74.2s
 GET /?isDebug=true 200 in 75529ms
 ○ Compiling /favicon.ico ...
watch error (["/home/ubuntu/app/.next-internal/server/app/favicon.ico"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" }) 
watch error (["/home/ubuntu/app/.next-internal/server/app/favicon.ico/route"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" }) 
 ✓ Compiled /favicon.ico in 10.8s
 GET /favicon.ico?favicon.45db1c09.ico 200 in 11531ms

next.config.ts

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  /* config options here */
  watchOptions: {
    pollIntervalMs: 1000, // some sensible number
  },
};

export default nextConfig;

pnpm-workspace.yaml

ignoredBuiltDependencies:
  - '@tailwindcss/oxide'

onlyBuiltDependencies:
  - sharp
  - unrs-resolver

publicHoistPattern:
  # pnpm v10+ doesn't hoist `eslint` by default, but we need it to be hoisted
  # @see https://github.com/pnpm/pnpm/issues/8878#issuecomment-2546442011
  - '*eslint*'
  # I added the two entries below to attempt to fix the watch errors but without success... Error logs are the same anyway.
  - '@opentelemetry'
  - '@swc'

It seems that enabling turbopack causes next.js to try to watch unknown/incorrect file paths:

ubuntu@510f15ec1d1b:~/app$ ls -al \
/home/ubuntu/app/node_modules/@opentelemetry \
/home/ubuntu/app/node_modules/@swc \
/home/ubuntu/app/.config \
/home/ubuntu/app/.next-internal \
/home/ubuntu/app/.next-internal/server \
/home/ubuntu/app/.next-internal/server/app \
/home/ubuntu/app/.next-internal/server/app/page
ls: cannot access '/home/ubuntu/app/node_modules/@opentelemetry': No such file or directory
ls: cannot access '/home/ubuntu/app/node_modules/@swc': No such file or directory
ls: cannot access '/home/ubuntu/app/.config': No such file or directory
ls: cannot access '/home/ubuntu/app/.next-internal': No such file or directory
ls: cannot access '/home/ubuntu/app/.next-internal/server': No such file or directory
ls: cannot access '/home/ubuntu/app/.next-internal/server/app': No such file or directory
ls: cannot access '/home/ubuntu/app/.next-internal/server/app/page': No such file or directory

ubuntu@510f15ec1d1b:~/app$ find . -name '@opentelemetry' -o -name '@swc' -o -name '.config' -o -name '.next-internal'
./node_modules/.pnpm/@swc+counter@0.1.3/node_modules/@swc
./node_modules/.pnpm/@swc+helpers@0.5.15/node_modules/@swc
./node_modules/.pnpm/next@15.3.3_react-dom@19.1.0_react@19.1.0__react@19.1.0/node_modules/@swc
./node_modules/.pnpm/next@15.3.3_react-dom@19.1.0_react@19.1.0__react@19.1.0/node_modules/next/dist/compiled/@opentelemetry
./node_modules/.pnpm/node_modules/@swc

See repro repo: kayhadrin/threejs-demo@7817931

[icyJoseph]

• Do you observe the same issue if you use plain npm?
• Even though it fails to watch those, it seems to work, right?
• @ForsakenHarmony sorry for the tag, but do you reckon you could take a look at this? is it a bug? have we forgotten to ignore certain files from watch?

[kayhadrin]

@icyJoseph:

• Do you observe the same issue if you use plain npm?

Yes, it's also not working with npm. I.e. Errors appear in console and changing a source file doesn't trigger anything from the next.js server.
Tested with --turbo and on kayhadrin/threejs-demo@7817931

$ npm run dev

   ▲ Next.js 15.3.3 (Turbopack)
   - Local:        http://localhost:3000
   - Network:      http://172.17.0.2:3000
   - Environments: .env.local

 ✓ Starting...
Attention: Next.js now collects completely anonymous telemetry regarding usage.
This information is used to shape Next.js' roadmap and prioritize features.
You can learn more, including how to opt-out if you'd not like to participate in this anonymous program, by visiting the following URL:
https://nextjs.org/telemetry

 ✓ Ready in 11.7s
 ○ Compiling / ...
watch error (["/home/ubuntu/app/node_modules/next/node_modules/@swc"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" })
watch error (["/home/ubuntu/app/node_modules/@opentelemetry"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" })
watch error (["/home/ubuntu/app/.config"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" })
watch error (["/home/ubuntu/app/.next-internal"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" })
watch error (["/home/ubuntu/app/.next-internal/server"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" })
watch error (["/home/ubuntu/app/.next-internal/server/app"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" })
watch error (["/home/ubuntu/app/.next-internal/server/app/page"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" })
 ✓ Compiled / in 11.3s
 GET / 200 in 12266ms
 ○ Compiling /favicon.ico ...
watch error (["/home/ubuntu/app/.next-internal/server/app/favicon.ico"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" })
watch error (["/home/ubuntu/app/.next-internal/server/app/favicon.ico/route"]): Io(Os { code: 2, kind: NotFound, message: "No such file or directory" })
 ✓ Compiled /favicon.ico in 3.2s
 GET /favicon.ico?favicon.45db1c09.ico 200 in 3694ms

---

• Even though it fails to watch those, it seems to work, right?

No, the file watch doesn't work when using WSL2+Docker with turbopack enabled while using the suggested watchOptions option in next.config.ts.