Permalink
Browse files

Docs: Add Troubleshoot section

Fix #1464
  • Loading branch information...
molant committed Nov 8, 2018
1 parent c52171b commit e56c6df5d135c9f26ee7fcfef9e19ffd8534236b
Showing with 76 additions and 39 deletions.
  1. +3 −39 packages/hint/docs/user-guide/index.md
  2. +73 −0 packages/hint/docs/user-guide/troubleshoot/summary.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.
<!-- Link labels: -->
[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
@@ -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.
<!-- Link labels: -->
[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

0 comments on commit e56c6df

Please sign in to comment.