Skip to content

docs: watchOptions.pollIntervalMs #80687

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
icyJoseph wants to merge 3 commits into
base: canary
Choose a base branch
from
Draft

docs: watchOptions.pollIntervalMs #80687

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dcb9ce8
docs: watchOptions.pollIntervalMs
icyJoseph Jun 19, 2025
a36cdb8
docs: Redundant millisecond statement
icyJoseph Jun 19, 2025
dc4d7a4
chore: watchOptions.pollIntervalMs applies to both Turbopack and webpack
icyJoseph Jun 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions docs/01-app/03-api-reference/05-config/01-next-config-js/watchOptions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
title: watchOptions
description: Enable file watch polling for Turbopack and Webpack.
---

Enable file watch polling for Turbopack and Webpack.

## Usage

The `watchOptions` option allows you to configure a file watching polling interval during development.

```ts filename="next.config.ts" switcher
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
watchOptions: {
pollIntervalMs: 1000,

@leerob leerob Jun 23, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the default value?

@icyJoseph icyJoseph Jun 23, 2025

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's None (rust pun) - The default behavior is to use the system file watcher. When that fails, users can pass the polling option.

In other words, as far as I understand this won't do anything.

const nextConfig: NextConfig = {
  watchOptions: {}
}

@icyJoseph icyJoseph Jun 23, 2025

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ForsakenHarmony could you confirm? :)

@ForsakenHarmony ForsakenHarmony Jul 2, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please don't ping me, I no longer work at vercel (and certainly don't remember details like that on a PR that's >6 months ago)

},
}

export default nextConfig
```

```js filename="next.config.js" switcher
/** @type {import('next').NextConfig} */
const nextConfig = {
watchOptions: {
pollIntervalMs: 1000,
},
}

module.exports = nextConfig
```

## Config options

- `pollIntervalMs`: How often to poll for file changes.

Polling is only enabled when the `watchOptions.pollIntervalMs` option is specified.

## When to use

Enable this option if you're running into issues where file changes are not being detected during development.

This can happen when working inside a VM, Docker container, or over a networked volume.

`watchOptions.pollIntervalMs` is passed to both Turbopack and Webpack.

## Version History

| Version | Changes |
| -------- | --------------------------------------- |
| `15.0.0` | `watchOptions.pollIntervalMs` is added. |