Permalink
Browse files

Docs: Add `Create a custom shareable configuration`

Fix #1442
Close #1478

Co-Authored-By: Cătălin Mariș <alrraa@gmail.com>
  • Loading branch information...
molant and alrra committed Nov 5, 2018
1 parent 8499d5c commit 306a3829af9e268cee36eaf1bf3be745894b001e
@@ -0,0 +1,117 @@
# Create a custom shareable configuration
If you use `webhint` in multiple projects you might want to share
the same configuration with all of them. An easy way to achieve this
is via shareable configurations.
The `webhint` team currently maintains a few of these packages:
* [`web-recommended`][configuration-web-recommended]
* [`progressive-web-apps`][configuration-progressive-web-apps]
* [`development`][configuration-development]
To use them you install one (or more) in your project using npmn and
`extend` them, e.g.:
```bash
npm install --save-dev `@hint/configuration-web-recommended`
```
And in your `.hintrc` add:
```json
{
"extends": ["web-recommended"]
}
```
One interesting thing that can be done with shared configurations is
to download all the required `connector`s, `formatter`s, `hint`s, and
`parser`s at the same time they get installed. This way you can guarantee
that all dependencies are satisfied and there are no configuration issues.
## Quick example
A shareable configuration npm package contains (at least) the following:
* `package.json`: All the required dependencies you want to get installed
automatically for this `configuration`.
* `index.json`: A `JSON` with the same format as a regular `.hintrc` file
with the configuration to be shared.
In order for `webhint` to find the package the name has to be:
* `@hint/configuration-NAME` if it is maintained officially by the
`webhint` team (you will not be able to publish to the `@hint` scope
unless you have the right privileges).
* `hint-configuration-NAME` if it is not.
Imagine you want to create a configuration that focuses only in security.
First you will create a new package in an empty folder:
```bash
mkdir hint-configuration-security
cd hint-configuration-security
npm init
```
Answer all the questions from the wizard making sure to:
* Set `index.json` as the entry point.
* Set the package name to `hint-configuration-security`.
Once this is done, add all the security hints you are interested in:
```bash
npm install --save-dev @hint/disown-opener @hint/https-only @hint/no-disallowed-headers ...
```
Do not forget to add a `connector` and a `formatter`. `jsdom` and `html`
are the examples in this case:
```bash
npm install --save-dev @hint/connector-jsdom @hint/formatter-html
```
Finally, create a new `index.json` in the root of the project with a
content similar to:
```json
{
"connector": "jsdom",
"formatters": ["html"],
"hints": {
"disown-opener": "error",
"https-only": "error",
"no-disallowed-headers": "error",
...
},
...
}
```
The package should be ready for publishing now and you can do it via
`npm publish`. There is more detailed information about this command
in [npm's publish documentation][npm publish].
To consume it you install it as follows in all the projects you want
to use it:
```bash
npm install hint-configuration-security
```
And create a `.hintrc` file in each one with this:
```json
{
"extends": ["configuration-security"]
}
```
<!-- Link labels -->
[configuration-development]: https://www.npmjs.com/package/@hint/configuration-development
[configuration-progressive-web-apps]: https://www.npmjs.com/package/@hint/configuration-progressive-web-apps
[configuration-web-recommended]: https://npmjs.com/package/@hint/configuration-web-recommended
[npm publish]: https://docs.npmjs.com/cli/publish
@@ -16,6 +16,7 @@ This section contains the basics to start hacking `webhint`:
The ins and outs of the different parts that make `webhint` plus some common scenarios:
* [Create a custom shareable configuration](./how-to/configuration.md)
* [Develop a connector](./how-to/connector.md)
* [Develop a formatter](./how-to/formatter.md)
* [Develop a parser](./how-to/parser.md)

0 comments on commit 306a382

Please sign in to comment.