diff --git a/packages/hint/docs/user-guide/index.md b/packages/hint/docs/user-guide/index.md index 0aa179d8666..b9501d20b7f 100644 --- a/packages/hint/docs/user-guide/index.md +++ b/packages/hint/docs/user-guide/index.md @@ -19,6 +19,9 @@ npm install -g --engine-strict hint You can also install it as a `devDependency` if you prefer not to have it globally (which is the team's preferred option). +**NOTE**: If you run into any issues during the install process +please check the [troubleshoot section](./troubleshoot/). + `webhint` needs a configuration file to know what `hint`s, `connector`s, etc. to use. By default it will look for a `.hintrc` file in the current folder and then in the user's home directory. @@ -98,47 +101,8 @@ about the different pieces: * [Formatters](./concepts/formatters/) * [Parsers](./concepts/parsers/) -### Windows and Python - -Depending on your environment you could get an error similar to the -following if there is a problem downloading any of the precompiled -native modules: - -> gyp ERR! stack Error: Can't find Python executable "python" - -The fastest way to have a Windows environment capable of compiling native -Node modules is installing the [`windows-build-tools`][windows build tools]. - -From an **Elevated PowerShell** run the following: - -```bash -npm install --global windows-build-tools -``` - -### Permission issues during installation - -If you receive an `EACCES` error when installing `webhint`, it is caused -by installing packages globally. The recommended solution is to [change -`npm`’s default directory][npm change default directory] and then try -again. There have been reports of this issue when installing the -dependency `canvas-prebuilt` throws an `EACCES`. This [issue][permission -issue] was resolved adopting the recommended solution. You can find -detailed steps on how to change the npm default directory [here][npm -change default directory]. According to [npm’s documentation][npm use -package manager], if you have node installed using a package -manager like [Homebrew][homebrew] or [nvm][nvm], you may be able to avoid -the trouble of messing with the directories and have the correct -permissions set up right out of the box. As a result, you will not -experience the error described above even if you install `webhint` -globally. - -[homebrew]: https://brew.sh/ [nodejs]: https://nodejs.org/en/download/current/ -[npm change default directory]: https://docs.npmjs.com/getting-started/fixing-npm-permissions#option-2-change-npms-default-directory-to-another-directory [npm use package manager]: https://docs.npmjs.com/getting-started/fixing-npm-permissions#option-3-use-a-package-manager-that-takes-care-of-this-for-you -[nvm]: https://github.com/creationix/nvm -[permission issue]: https://github.com/webhintio/hint/issues/308 [web recommended]: https://github.com/webhintio/hint/blob/master/packages/configuration-web-recommended/index.json -[windows build tools]: https://www.npmjs.com/package/windows-build-tools diff --git a/packages/hint/docs/user-guide/troubleshoot/summary.md b/packages/hint/docs/user-guide/troubleshoot/summary.md new file mode 100644 index 00000000000..268b2848f65 --- /dev/null +++ b/packages/hint/docs/user-guide/troubleshoot/summary.md @@ -0,0 +1,73 @@ +# Common issues when installing or running webhint + +While the team has made progress in removing the possibilities of +running into issues while installing the project, you could still +run into some issues especially when dealing with binary packages +(`canvas` and `iltorb` are the currently used ones). + +This section contains the most commons issues reported by users with +potential fixes. If you run into something that is not documented +here please [open an issue in the hint repo][new issue]. + +## Building Windows packages + +Depending on your environment you could get an error similar to the +following if there is a problem downloading any of the precompiled +native modules: + +> gyp ERR! stack Error: Can't find Python executable "python" + +Newer versions of node (10+) on Windows ask users if they want the installer +to automatically install the required dependencies. You can use this method +or you can also install the [`windows-build-tools`][windows build tools]. +From an **Elevated PowerShell** run the following: + +```bash +npm install --global windows-build-tools +``` + +## Issues with `canvas` + +Starting on `connector-jsdom v1.1.0`, `canvas` was changed to be an optional +dependency so while you might see some issues during the installation if the +binary is not available for download, the overall process should finish and +you should be able to execute `webhint` using the `jsdom` connector. The only caveat +is that images will not be downloaded. + +This error happens more often: + +* when there is a new release of node and precompiled binaries for `canvas` + are not yet available. +* if you are running node x86 on Windows. The recommendation is to switch to + x64 as [it is unlikely there will be x86 binaries any time soon][canvas x86]. + +You can also compile it yourself by following the [instructions][canvas compile]. + +## Permission issues during installation + +If you receive an `EACCES` error when installing `webhint`, it is caused +by installing packages globally. The recommended solution is to [change +`npm`’s default directory][npm change default directory] and then try +again. There have been reports of this issue when installing the +dependency `canvas` throws an `EACCES`. This [issue][permission +issue] was resolved adopting the recommended solution. You can find +detailed steps on how to change the npm default directory [here][npm +change default directory]. According to [npm’s documentation][npm use +package manager], if you have node installed using a package +manager like [Homebrew][homebrew] or [nvm][nvm], you may be able to avoid +the trouble of messing with the directories and have the correct +permissions set up right out of the box. As a result, you will not +experience the error described above even if you install `webhint` +globally. + + + +[canvas compile]: https://github.com/Automattic/node-canvas#compiling +[canvas x86]: https://github.com/node-gfx/node-canvas-prebuilt/issues/27#issuecomment-348037675 +[homebrew]: https://brew.sh/ +[new issue]: https://github.com/webhintio/hint/issues/new +[npm change default directory]: https://docs.npmjs.com/getting-started/fixing-npm-permissions#option-2-change-npms-default-directory-to-another-directory +[nvm]: https://github.com/creationix/nvm +[optional canvas]: https://github.com/webhintio/hint/commit/47d51aeaa187351267f7b4cabd3f075de49d043d +[permission issue]: https://github.com/webhintio/hint/issues/308 +[windows build tools]: https://www.npmjs.com/package/windows-build-tools