Skip to content
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.

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

docs: update WSL2 watch limitation explanation #8939

Merged
merged 11 commits into from
Aug 13, 2022

Conversation

sapphi-red
Copy link
Member

@sapphi-red sapphi-red commented Jul 5, 2022

Description

This PR adds the following warning for WSL2 when usePolling is not set. I'm not sure if it is good to have this warning for all WSL2 users.

(!) Default file system watching might not work with your setup due to the limitation of WSL2. HMR and other features will not work when file system watching is not working. To suppress this warning, set true or false to "server.watch.usePolling". More information: https://vitejs.dev/config/server-options.html#server-watch

Also this PR improves the document about that.

This also applies to docker with WSL2 backend and docker running on WSL2 directly.

refs #4116

Additional context

At first I thought it is able to detect the case if file system watching works or not.
But after implemented that, I noticed that the document is not correct.
The current explanation is:

When running Vite on Windows Subsystem for Linux (WSL) 2, if the project folder resides in a Windows filesystem

But actually it is:

When running Vite on WSL2 and a file is edited by Windows applications (non WSL2 process)

The former one is possible to detect, but the latter one is not possible since Vite runs as a WSL2 process or Windows process.
We could start a powershell process from Vite but that won't work with Docker(WSL2 backend).

One way to implement is to show this warning if any file change was not detected after some time.


What is the purpose of this pull request?

  • Bug fix
  • New Feature
  • Documentation update
  • Other

Before submitting the PR, please make sure you do the following

  • Read the Contributing Guidelines.
  • Read the Pull Request Guidelines and follow the Commit Convention.
  • Check that there isn't already a PR that solves the problem the same way to avoid creating a duplicate.
  • Provide a description in this PR that addresses what the PR is solving, or reference the issue that it solves (e.g. fixes #123).
  • Ideally, include relevant tests that fail without this PR but pass with it.

@sapphi-red sapphi-red added documentation Improvements or additions to documentation windows only feat: hmr p2-nice-to-have Not breaking anything but nice to have (priority) labels Jul 5, 2022
@netlify
Copy link

netlify bot commented Jul 5, 2022

Deploy Preview for vite-docs-main canceled.

Name Link
🔨 Latest commit 608181c
🔍 Latest deploy log https://app.netlify.com/sites/vite-docs-main/deploys/62cb0166e6b7f10008368718

The current detection somehow works with docker+wsl2, but it does not work with wsl2.
@sapphi-red sapphi-red changed the title feat: warn if watcher is not working on WSL2 feat: warn if usePolling is not set and WSL2 is used Jul 9, 2022
@sapphi-red sapphi-red changed the title feat: warn if usePolling is not set and WSL2 is used feat: warn if usePolling is not set on WSL2 Jul 9, 2022
@sapphi-red sapphi-red marked this pull request as ready for review July 9, 2022 17:17
packages/vite/src/node/build.ts Outdated Show resolved Hide resolved
docs/config/server-options.md Outdated Show resolved Hide resolved
packages/vite/src/node/build.ts Outdated Show resolved Hide resolved
sapphi-red and others added 3 commits July 11, 2022 01:29
Co-authored-by: Bjorn Lu <bjornlu.dev@gmail.com>
Co-authored-by: Bjorn Lu <bjornlu.dev@gmail.com>
bluwy
bluwy previously approved these changes Jul 11, 2022
Copy link
Member

@bluwy bluwy left a comment

Choose a reason for hiding this comment

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

Neat!

@sapphi-red
Copy link
Member Author

I reconsidered that the warning is too noisy and removed it.

@sapphi-red sapphi-red changed the title feat: warn if usePolling is not set on WSL2 docs: update WSL2 watch limitation explanation Aug 11, 2022
@sapphi-red sapphi-red added p1-chore Doesn't change code behavior (priority) and removed p2-nice-to-have Not breaking anything but nice to have (priority) labels Aug 11, 2022
@patak-dev
Copy link
Member

patak-dev commented Aug 13, 2022

Maybe there could be an short entry in troubleshouting pointing to these sections too?

Ah, I see there is already a section https://vitejs.dev/guide/troubleshooting.html#vite-does-not-detect-a-file-change

@patak-dev patak-dev merged commit afbb87d into vitejs:main Aug 13, 2022
@sapphi-red sapphi-red deleted the feat/wsl2-watch-warning branch August 18, 2022 11:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation feat: hmr p1-chore Doesn't change code behavior (priority) windows only
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants