1 | <h1 align="center">
|
2 | <a href="https://standardjs.com"><img src="https://cdn.rawgit.com/standard/standard/master/sticker.svg" alt="Standard - JavaScript Style Guide" width="200"></a>
|
3 | <br>
|
4 | JavaScript Standard Style
|
5 | <br>
|
6 | <br>
|
7 | </h1>
|
8 |
|
9 | <p align="center">
|
10 | <a href="https://discord.gg/ZegqCBr"><img src="https://img.shields.io/discord/612704110008991783" alt="discord"></a>
|
11 | <a href="https://travis-ci.org/standard/standard"><img src="https://img.shields.io/travis/standard/standard/master.svg" alt="travis"></a>
|
12 | <a href="https://www.npmjs.com/package/standard"><img src="https://img.shields.io/npm/v/standard.svg" alt="npm version"></a>
|
13 | <a href="https://www.npmjs.com/package/eslint-config-standard"><img src="https://img.shields.io/npm/dm/eslint-config-standard.svg" alt="npm downloads"></a>
|
14 | <a href="https://standardjs.com"><img src="https://img.shields.io/badge/code_style-standard-brightgreen.svg" alt="Standard - JavaScript Style Guide"></a>
|
15 | </p>
|
16 |
|
17 | <p align="center">
|
18 | <a href="/docs/README-en.md">English</a> •
|
19 | <a href="/docs/README-esla.md">Español (Latinoamérica)</a> •
|
20 | <a href="/docs/README-fr.md">Français</a> •
|
21 | <a href="/docs/README-iteu.md">Italiano (Italian)</a> •
|
22 | <a href="/docs/README-ja.md">日本語 (Japanese)</a> •
|
23 | <a href="/docs/README-kokr.md">한국어 (Korean)</a> •
|
24 | <a href="/docs/README-ptbr.md">Português (Brasil)</a> •
|
25 | <a href="/docs/README-zhcn.md">简体中文 (Simplified Chinese)</a> •
|
26 | <a href="/docs/README-zhtw.md">繁體中文 (Taiwanese Mandarin)</a>
|
27 | </p>
|
28 |
|
29 | ## JavaScript style guide, linter, and formatter
|
30 |
|
31 | This module saves you (and others!) time in three ways:
|
32 |
|
33 | - **No configuration.** The easiest way to enforce code quality in your
|
34 | project. No decisions to make. No `.eslintrc` files to manage. It just works.
|
35 | - **Automatically format code.** Just run `standard --fix` and say goodbye to
|
36 | messy or inconsistent code.
|
37 | - **Catch style issues & programmer errors early.** Save precious code review
|
38 | time by eliminating back-and-forth between reviewer & contributor.
|
39 |
|
40 | Give it a try by running `npx standard --fix` right now!
|
41 |
|
42 | ## Table of Contents
|
43 |
|
44 | - Quick start
|
45 | - [Install](#install)
|
46 | - [Usage](#usage)
|
47 | - [What you might do if you're clever](#what-you-might-do-if-youre-clever)
|
48 | - FAQ
|
49 | - [Why should I use JavaScript Standard Style?](#why-should-i-use-javascript-standard-style)
|
50 | - [Who uses JavaScript Standard Style?](#who-uses-javascript-standard-style)
|
51 | - [Are there text editor plugins?](#are-there-text-editor-plugins)
|
52 | - [Is there a readme badge?](#is-there-a-readme-badge)
|
53 | - [I disagree with rule X, can you change it?](#i-disagree-with-rule-x-can-you-change-it)
|
54 | - [But this isn't a real web standard!](#but-this-isnt-a-real-web-standard)
|
55 | - [Is there an automatic formatter?](#is-there-an-automatic-formatter)
|
56 | - [How do I ignore files?](#how-do-i-ignore-files)
|
57 | - [How do I hide a certain warning?](#how-do-i-hide-a-certain-warning)
|
58 | - [I use a library that pollutes the global namespace. How do I prevent "variable is not defined" errors?](#i-use-a-library-that-pollutes-the-global-namespace-how-do-i-prevent-variable-is-not-defined-errors)
|
59 | - [How do I use experimental JavaScript (ES Next) features?](#how-do-i-use-experimental-javascript-es-next-features)
|
60 | - [Can I use a JavaScript language variant, like Flow or TypeScript?](#can-i-use-a-javascript-language-variant-like-flow-or-typescript)
|
61 | - [What about Mocha, Jest, Jasmine, QUnit, etc?](#what-about-mocha-jest-jasmine-qunit-etc)
|
62 | - [What about Web Workers and Service Workers?](#what-about-web-workers-and-service-workers)
|
63 | - [Can I check code inside of Markdown or HTML files?](#can-i-check-code-inside-of-markdown-or-html-files)
|
64 | - [Is there a Git `pre-commit` hook?](#is-there-a-git-pre-commit-hook)
|
65 | - [How do I make the output all colorful and pretty?](#how-do-i-make-the-output-all-colorful-and-pretty)
|
66 | - [Is there a Node.js API?](#is-there-a-nodejs-api)
|
67 | - [How do I contribute to StandardJS?](#how-do-i-contribute-to-standardjs)
|
68 | - [License](#license)
|
69 |
|
70 | ## Install
|
71 |
|
72 | The easiest way to use JavaScript Standard Style is to install it globally as a
|
73 | Node command line program. Run the following command in Terminal:
|
74 |
|
75 | ```bash
|
76 | $ npm install standard --global
|
77 | ```
|
78 |
|
79 | Or, you can install `standard` locally, for use in a single project:
|
80 |
|
81 | ```bash
|
82 | $ npm install standard --save-dev
|
83 | ```
|
84 |
|
85 | *Note: To run the preceding commands, [Node.js](http://nodejs.org) and [npm](https://npmjs.com) must be installed.*
|
86 |
|
87 | ## Usage
|
88 |
|
89 | After you've installed `standard`, you should be able to use the `standard` program. The
|
90 | simplest use case would be checking the style of all JavaScript files in the
|
91 | current working directory:
|
92 |
|
93 | ```bash
|
94 | $ standard
|
95 | Error: Use JavaScript Standard Style
|
96 | lib/torrent.js:950:11: Expected '===' and instead saw '=='.
|
97 | ```
|
98 |
|
99 | If you've installed `standard` locally, run with `npx` instead:
|
100 |
|
101 | ```bash
|
102 | $ npx standard
|
103 | ```
|
104 |
|
105 | You can optionally pass in a directory (or directories) using the glob pattern. Be
|
106 | sure to quote paths containing glob patterns so that they are expanded by
|
107 | `standard` instead of your shell:
|
108 |
|
109 | ```bash
|
110 | $ standard "src/util/**/*.js" "test/**/*.js"
|
111 | ```
|
112 |
|
113 | **Note:** by default `standard` will look for all files matching the patterns:
|
114 | `**/*.js`, `**/*.jsx`.
|
115 |
|
116 | ## What you might do if you're clever
|
117 |
|
118 | 1. Add it to `package.json`
|
119 |
|
120 | ```json
|
121 | {
|
122 | "name": "my-cool-package",
|
123 | "devDependencies": {
|
124 | "standard": "*"
|
125 | },
|
126 | "scripts": {
|
127 | "test": "standard && node my-tests.js"
|
128 | }
|
129 | }
|
130 | ```
|
131 |
|
132 | 2. Style is checked automatically when you run `npm test`
|
133 |
|
134 | ```bash
|
135 | $ npm test
|
136 | Error: Use JavaScript Standard Style
|
137 | lib/torrent.js:950:11: Expected '===' and instead saw '=='.
|
138 | ```
|
139 |
|
140 | 3. Never give style feedback on a pull request again!
|
141 |
|
142 | ## Why should I use JavaScript Standard Style?
|
143 |
|
144 | The beauty of JavaScript Standard Style is that it's simple. No one wants to
|
145 | maintain multiple hundred-line style configuration files for every module/project
|
146 | they work on. Enough of this madness!
|
147 |
|
148 | This module saves you (and others!) time in three ways:
|
149 |
|
150 | - **No configuration.** The easiest way to enforce consistent style in your
|
151 | project. Just drop it in.
|
152 | - **Automatically format code.** Just run `standard --fix` and say goodbye to
|
153 | messy or inconsistent code.
|
154 | - **Catch style issues & programmer errors early.** Save precious code review
|
155 | time by eliminating back-and-forth between reviewer & contributor.
|
156 |
|
157 | Adopting `standard` style means ranking the importance of code clarity and
|
158 | community conventions higher than personal style. This might not make sense for
|
159 | 100% of projects and development cultures, however open source can be a hostile
|
160 | place for newbies. Setting up clear, automated contributor expectations makes a
|
161 | project healthier.
|
162 |
|
163 | For more info, see the conference talk ["Write Perfect Code with Standard and
|
164 | ESLint"](https://www.youtube.com/watch?v=kuHfMw8j4xk). In this talk, you'll learn
|
165 | about linting, when to use `standard` versus `eslint`, and how `prettier` compares
|
166 | to `standard`.
|
167 |
|
168 | ## Who uses JavaScript Standard Style?
|
169 |
|
170 | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/nodejs.png>](https://nodejs.org) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/npm.png>](https://www.npmjs.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/github.png>](https://github.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/elastic.png>](https://www.elastic.co) |
|
171 | |---|---|---|---|
|
172 |
|
173 | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/express.png>](http://expressjs.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/electron.png>](http://electron.atom.io) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/nuxtjs.png>](https://nuxtjs.org/) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/atom.png>](https://atom.io) |
|
174 | |---|---|---|---|
|
175 |
|
176 | | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/mongodb.jpg>](https://www.mongodb.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/zendesk.png>](https://www.zendesk.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/brave.png>](https://www.brave.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/zeit.png>](https://zeit.co) |
|
177 | |---|---|---|---|
|
178 |
|
179 | | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/nodesource.png>](https://nodesource.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/nearform.png>](http://www.nearform.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/typeform.png>](https://www.typeform.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/gov-uk.png>](https://gds.blog.gov.uk) |
|
180 | |---|---|---|---|
|
181 |
|
182 | | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/heroku.png>](https://www.heroku.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/saucelabs.png>](https://saucelabs.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/automattic.png>](https://automattic.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/godaddy.png>](https://www.godaddy.com) |
|
183 | |---|---|---|---|
|
184 |
|
185 | | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/webtorrent.png>](https://webtorrent.io) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/ipfs.png>](https://ipfs.io) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/dat.png>](https://datproject.org) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/bitcoinjs.png>](https://bitcoinjs.org) |
|
186 | |---|---|---|---|
|
187 |
|
188 | | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/voltra.png>](https://voltra.co) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/treasuredata.png>](https://www.treasuredata.com) | [<img alt="Free MIDIs, MIDI file downloads" width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/bitmidi.png>](https://bitmidi.com) | [<img width=190 alt="College essays, AP notes" src=https://cdn.rawgit.com/standard/standard/master/docs/logos/studynotes.jpg>](https://www.apstudynotes.org) |
|
189 | |---|---|---|---|
|
190 |
|
191 | | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/optiopay.png>](https://www.optiopay.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/jaguar-landrover.png>](https://www.jlrtechincubator.com/jlrti/) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/bustle.jpg>](https://www.bustle.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/zentrick.png>](https://www.zentrick.com) |
|
192 | |---|---|---|---|
|
193 |
|
194 | | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/greenkeeper.png>](https://greenkeeper.io) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/karma.png>](https://karma-runner.github.io) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/taser.png>](https://www.taser.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/neo4j.png>](https://www.neo4j.com) |
|
195 | |---|---|---|---|
|
196 |
|
197 | | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/rentograph.png>](https://rentograph.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/eaze.png>](https://www.eaze.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/ctrl-alt-deseat.png>](https://www.ctrlaltdeseat.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/clevertech.png>](https://clevertech.biz) |
|
198 | |---|---|---|---|
|
199 |
|
200 | | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/aragon.png>](https://aragon.org) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/flowsent.png>](https://www.flowsent.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/puma-browser.png>](https://www.pumabrowser.com/) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/webstorm.png>](https://www.jetbrains.com/webstorm/) |
|
201 | |---|---|---|---|
|
202 |
|
203 |
|
204 | | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/fastify.png>](https://www.fastify.io) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/scuttlebutt.png>](https://www.scuttlebutt.nz) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/solid.png>](https://solid.inrupt.com) | [<img width=190 src=https://cdn.rawgit.com/standard/standard/master/docs/logos/grab.png>](https://www.grab.com) |
|
205 | |---|---|---|---|
|
206 |
|
207 |
|
208 | | Your logo here | Your logo here | Your logo here | Your logo here |
|
209 | |---|---|---|---|
|
210 |
|
211 |
|
212 | In addition to companies, many community members use `standard` on packages that
|
213 | are [too numerous](https://raw.githubusercontent.com/standard/standard-packages/master/all.json)
|
214 | to list here.
|
215 |
|
216 | `standard` is also the top-starred linter in GitHub's
|
217 | [Clean Code Linter](https://github.com/showcases/clean-code-linters) showcase.
|
218 |
|
219 | ## Are there text editor plugins?
|
220 |
|
221 | First, install `standard`. Then, install the appropriate plugin for your editor:
|
222 |
|
223 | ### Sublime Text
|
224 |
|
225 | Using **[Package Control][sublime-1]**, install **[SublimeLinter][sublime-2]** and
|
226 | **[SublimeLinter-contrib-standard][sublime-3]**.
|
227 |
|
228 | For automatic formatting on save, install **[StandardFormat][sublime-4]**.
|
229 |
|
230 | [sublime-1]: https://packagecontrol.io/
|
231 | [sublime-2]: http://www.sublimelinter.com/en/latest/
|
232 | [sublime-3]: https://packagecontrol.io/packages/SublimeLinter-contrib-standard
|
233 | [sublime-4]: https://packagecontrol.io/packages/StandardFormat
|
234 |
|
235 | ### Atom
|
236 |
|
237 | Install **[linter-js-standard][atom-1]**.
|
238 |
|
239 | Alternatively, you can install **[linter-js-standard-engine][atom-4]**. Instead of
|
240 | bundling a version of `standard` it will automatically use the version installed
|
241 | in your current project. It will also work out of the box with other linters based
|
242 | on **[standard-engine][atom-5]**.
|
243 |
|
244 | For automatic formatting, install **[standard-formatter][atom-2]**. For snippets,
|
245 | install **[standardjs-snippets][atom-3]**.
|
246 |
|
247 | [atom-1]: https://atom.io/packages/linter-js-standard
|
248 | [atom-2]: https://atom.io/packages/standard-formatter
|
249 | [atom-3]: https://atom.io/packages/standardjs-snippets
|
250 | [atom-4]: https://atom.io/packages/linter-js-standard-engine
|
251 | [atom-5]: https://github.com/standard/standard-engine
|
252 |
|
253 | ### Visual Studio Code
|
254 |
|
255 | Install **[vscode-standardjs][vscode-1]**. (Includes support for automatic formatting.)
|
256 |
|
257 | For JS snippets, install: **[vscode-standardjs-snippets][vscode-2]**. For React snippets, install **[vscode-react-standard][vscode-3]**.
|
258 |
|
259 | [vscode-1]: https://marketplace.visualstudio.com/items/chenxsan.vscode-standardjs
|
260 | [vscode-2]: https://marketplace.visualstudio.com/items?itemName=capaj.vscode-standardjs-snippets
|
261 | [vscode-3]: https://marketplace.visualstudio.com/items/TimonVS.ReactSnippetsStandard
|
262 |
|
263 | ### Vim
|
264 |
|
265 | Install **[ale][vim-1]**. And add these lines to your `.vimrc` file.
|
266 |
|
267 | ```vim
|
268 | let g:ale_linters = {
|
269 | \ 'javascript': ['standard'],
|
270 | \}
|
271 | let g:ale_fixers = {'javascript': ['standard']}
|
272 | ```
|
273 |
|
274 | This sets standard as your only linter and fixer for javascript files and so prevents conflicts with eslint. For linting and automatic fixing on save, add these lines to `.vimrc`:
|
275 | ```vim
|
276 | let g:ale_lint_on_save = 1
|
277 | let g:ale_fix_on_save = 1
|
278 | ```
|
279 |
|
280 |
|
281 | Alternative plugins to consider include [neomake][vim-2] and [syntastic][vim-3], both of which have built-in support for `standard` (though configuration may be necessary).
|
282 |
|
283 | [vim-1]: https://github.com/w0rp/ale
|
284 | [vim-2]: https://github.com/neomake/neomake
|
285 | [vim-3]: https://github.com/vim-syntastic/syntastic
|
286 |
|
287 | ### Emacs
|
288 |
|
289 | Install **[Flycheck][emacs-1]** and check out the **[manual][emacs-2]** to learn
|
290 | how to enable it in your projects.
|
291 |
|
292 | [emacs-1]: http://www.flycheck.org
|
293 | [emacs-2]: http://www.flycheck.org/en/latest/user/installation.html
|
294 |
|
295 | ### Brackets
|
296 |
|
297 | Search the extension registry for **["Standard Code Style"][brackets-1]** and click "Install".
|
298 |
|
299 | [brackets-1]: https://github.com/ishamf/brackets-standard/
|
300 |
|
301 | ### WebStorm (PhpStorm, IntelliJ, RubyMine, JetBrains, etc.)
|
302 |
|
303 | WebStorm [recently announced native support](https://blog.jetbrains.com/webstorm/2017/01/webstorm-2017-1-eap-171-2272/)
|
304 | for `standard` directly in the IDE.
|
305 |
|
306 | If you still prefer to configure `standard` manually, [follow this guide][webstorm-1]. This applies to all JetBrains products, including PhpStorm, IntelliJ, RubyMine, etc.
|
307 |
|
308 | [webstorm-1]: docs/webstorm.md
|
309 |
|
310 | ## Is there a readme badge?
|
311 |
|
312 | Yes! If you use `standard` in your project, you can include one of these badges in
|
313 | your readme to let people know that your code is using the standard style.
|
314 |
|
315 | [![JavaScript Style Guide](https://cdn.rawgit.com/standard/standard/master/badge.svg)](https://github.com/standard/standard)
|
316 |
|
317 | ```md
|
318 | [![JavaScript Style Guide](https://cdn.rawgit.com/standard/standard/master/badge.svg)](https://github.com/standard/standard)
|
319 | ```
|
320 |
|
321 | [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
|
322 |
|
323 | ```md
|
324 | [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
|
325 | ```
|
326 |
|
327 | ## I disagree with rule X, can you change it?
|
328 |
|
329 | No. The whole point of `standard` is to save you time by avoiding
|
330 | [bikeshedding][bikeshedding] about code style. There are lots of debates online about
|
331 | tabs vs. spaces, etc. that will never be resolved. These debates just distract from
|
332 | getting stuff done. At the end of the day you have to 'just pick something', and
|
333 | that's the whole philosophy of `standard` -- its a bunch of sensible 'just pick
|
334 | something' opinions. Hopefully, users see the value in that over defending their
|
335 | own opinions.
|
336 |
|
337 | There are a couple of similar packages for anyone who does not want to completely accept `standard`:
|
338 | - [semistandard](https://github.com/standard/semistandard) - standard, with semicolons
|
339 | - [standardx](https://github.com/standard/standardx) - standard, with custom tweaks
|
340 |
|
341 | If you really want to configure hundreds of ESLint rules individually, you can
|
342 | always use `eslint` directly with
|
343 | [eslint-config-standard](https://github.com/standard/eslint-config-standard) to
|
344 | layer your changes on top.
|
345 | [`standard-eject`](https://github.com/josephfrazier/standard-eject) can help
|
346 | you migrate from `standard` to `eslint` and `eslint-config-standard`.
|
347 |
|
348 | Pro tip: Just use `standard` and move on. There are actual real problems that you
|
349 | could spend your time solving! :P
|
350 |
|
351 | [bikeshedding]: https://www.freebsd.org/doc/en/books/faq/misc.html#bikeshed-painting
|
352 |
|
353 | ## But this isn't a real web standard!
|
354 |
|
355 | Of course it's not! The style laid out here is not affiliated with any official web
|
356 | standards groups, which is why this repo is called `standard/standard` and not
|
357 | `ECMA/standard`.
|
358 |
|
359 | The word "standard" has more meanings than just "web standard" :-) For example:
|
360 |
|
361 | - This module helps hold our code to a high *standard of quality*.
|
362 | - This module ensures that new contributors follow some basic *style standards*.
|
363 |
|
364 | ## Is there an automatic formatter?
|
365 |
|
366 | Yes! You can use `standard --fix` to fix most issues automatically.
|
367 |
|
368 | `standard --fix` is built into `standard` for maximum convenience. Most problems
|
369 | are fixable, but some errors (like forgetting to handle errors) must be fixed
|
370 | manually.
|
371 |
|
372 | To save you time, `standard` outputs the message "`Run standard --fix to
|
373 | automatically fix some problems`" when it detects problems that can be fixed
|
374 | automatically.
|
375 |
|
376 | ## How do I ignore files?
|
377 |
|
378 | Certain paths (`node_modules/`, `coverage/`, `vendor/`, `*.min.js`, `bundle.js`,
|
379 | and files/folders that begin with `.` like `.git/`) are automatically ignored.
|
380 |
|
381 | Paths in a project's root `.gitignore` file are also automatically ignored.
|
382 |
|
383 | Sometimes you need to ignore additional folders or specific minified files. To do
|
384 | that, add a `standard.ignore` property to `package.json`:
|
385 |
|
386 | ```json
|
387 | "standard": {
|
388 | "ignore": [
|
389 | "**/out/",
|
390 | "/lib/select2/",
|
391 | "/lib/ckeditor/",
|
392 | "tmp.js"
|
393 | ]
|
394 | }
|
395 | ```
|
396 |
|
397 | ## How do I hide a certain warning?
|
398 |
|
399 | In rare cases, you'll need to break a rule and hide the warning generated by
|
400 | `standard`.
|
401 |
|
402 | JavaScript Standard Style uses [ESLint](http://eslint.org/) under-the-hood and
|
403 | you can hide warnings as you normally would if you used ESLint directly.
|
404 |
|
405 | To get verbose output (so you can find the particular rule name to ignore), run:
|
406 |
|
407 | ```bash
|
408 | $ standard --verbose
|
409 | Error: Use JavaScript Standard Style
|
410 | routes/error.js:20:36: 'file' was used before it was defined. (no-use-before-define)
|
411 | ```
|
412 |
|
413 | Disable **all rules** on a specific line:
|
414 |
|
415 | ```js
|
416 | file = 'I know what I am doing' // eslint-disable-line
|
417 | ```
|
418 |
|
419 | Or, disable **only** the `"no-use-before-define"` rule:
|
420 |
|
421 | ```js
|
422 | file = 'I know what I am doing' // eslint-disable-line no-use-before-define
|
423 | ```
|
424 |
|
425 | Or, disable the `"no-use-before-define"` rule for **multiple lines**:
|
426 |
|
427 | ```js
|
428 | /* eslint-disable no-use-before-define */
|
429 | console.log('offending code goes here...')
|
430 | console.log('offending code goes here...')
|
431 | console.log('offending code goes here...')
|
432 | /* eslint-enable no-use-before-define */
|
433 | ```
|
434 |
|
435 | ## I use a library that pollutes the global namespace. How do I prevent "variable is not defined" errors?
|
436 |
|
437 | Some packages (e.g. `mocha`) put their functions (e.g. `describe`, `it`) on the
|
438 | global object (poor form!). Since these functions are not defined or `require`'d
|
439 | anywhere in your code, `standard` will warn that you're using a variable that is
|
440 | not defined (usually, this rule is really useful for catching typos!). But we want
|
441 | to disable it for these global variables.
|
442 |
|
443 | To let `standard` (as well as humans reading your code) know that certain variables
|
444 | are global in your code, add this to the top of your file:
|
445 |
|
446 | ```js
|
447 | /* global myVar1, myVar2 */
|
448 | ```
|
449 |
|
450 | If you have hundreds of files, it may be desirable to avoid adding comments to
|
451 | every file. In this case, run:
|
452 |
|
453 | ```bash
|
454 | $ standard --global myVar1 --global myVar2
|
455 | ```
|
456 |
|
457 | Or, add this to `package.json`:
|
458 |
|
459 | ```json
|
460 | {
|
461 | "standard": {
|
462 | "globals": [ "myVar1", "myVar2" ]
|
463 | }
|
464 | }
|
465 | ```
|
466 |
|
467 | *Note: `global` and `globals` are equivalent.*
|
468 |
|
469 | ## How do I use experimental JavaScript (ES Next) features?
|
470 |
|
471 | `standard` supports the latest ECMAScript features, ES8 (ES2017), including
|
472 | language feature proposals that are in "Stage 4" of the proposal process.
|
473 |
|
474 | To support experimental language features, `standard` supports specifying a
|
475 | custom JavaScript parser. Before using a custom parser, consider whether the added
|
476 | complexity is worth it.
|
477 |
|
478 | To use a custom parser, first install it from npm:
|
479 |
|
480 | ```bash
|
481 | npm install babel-eslint --save-dev
|
482 | ```
|
483 |
|
484 | Then run:
|
485 |
|
486 | ```bash
|
487 | $ standard --parser babel-eslint
|
488 | ```
|
489 |
|
490 | Or, add this to `package.json`:
|
491 |
|
492 | ```json
|
493 | {
|
494 | "standard": {
|
495 | "parser": "babel-eslint"
|
496 | }
|
497 | }
|
498 | ```
|
499 |
|
500 | ## Can I use a JavaScript language variant, like Flow or TypeScript?
|
501 |
|
502 | `standard` supports the latest ECMAScript features. However, Flow and TypeScript add new
|
503 | syntax to the language, so they are not supported out-of-the-box.
|
504 |
|
505 | To support JavaScript language variants, `standard` supports specifying a custom JavaScript
|
506 | parser as well as an ESLint plugin to handle the changed syntax. Before using a JavaScript
|
507 | language variant, consider whether the added complexity is worth it.
|
508 |
|
509 | ### Flow
|
510 |
|
511 | To use Flow, you need to run `standard` with `babel-eslint` as the parser and
|
512 | `eslint-plugin-flowtype` as a plugin.
|
513 |
|
514 | ```bash
|
515 | npm install babel-eslint eslint-plugin-flowtype --save-dev
|
516 | ```
|
517 |
|
518 | Then run:
|
519 |
|
520 | ```bash
|
521 | $ standard --parser babel-eslint --plugin flowtype
|
522 | ```
|
523 |
|
524 | Or, add this to `package.json`:
|
525 |
|
526 | ```json
|
527 | {
|
528 | "standard": {
|
529 | "parser": "babel-eslint",
|
530 | "plugins": [ "flowtype" ]
|
531 | }
|
532 | }
|
533 | ```
|
534 |
|
535 | *Note: `plugin` and `plugins` are equivalent.*
|
536 |
|
537 | ### TypeScript
|
538 |
|
539 | To use TypeScript, you need to run `standard` with `@typescript-eslint/parser` as the parser,
|
540 | `@typescript-eslint/eslint-plugin` as a plugin, and tell standard to lint `**/*.ts` files (since it
|
541 | doesn't by default).
|
542 |
|
543 | Unfortunately, there's an outstanding [issue](https://github.com/standard/standard/issues/1283)
|
544 | with `standard` and Typescript where `standard` would incorrectly emit unused-variable errors
|
545 | (e.g: when you import interfaces). And as a workaround, you need to use
|
546 | [standardx](https://github.com/standard/standardx) instead:sweat_smile:.
|
547 |
|
548 | ```bash
|
549 | npm install standardx @typescript-eslint/parser @typescript-eslint/eslint-plugin --save-dev
|
550 | ```
|
551 |
|
552 | Then run:
|
553 |
|
554 | ```bash
|
555 | $ standardx --parser @typescript-eslint/parser --plugin @typescript-eslint/eslint-plugin **/*.ts
|
556 | ```
|
557 |
|
558 | Or, add this to `package.json`:
|
559 |
|
560 | ```json
|
561 | {
|
562 | "eslintConfig": {
|
563 | "rules": {
|
564 | "no-unused-vars": "off",
|
565 | "@typescript-eslint/no-unused-vars": "error"
|
566 | }
|
567 | },
|
568 | "standardx": {
|
569 | "parser": "@typescript-eslint/parser",
|
570 | "plugins": [ "@typescript-eslint/eslint-plugin" ]
|
571 | }
|
572 | }
|
573 | ```
|
574 |
|
575 | With that in `package.json`, you can run:
|
576 |
|
577 | ```bash
|
578 | standardx **/*.ts
|
579 | ```
|
580 |
|
581 | And you probably should remove `standard` too to avoid confusion where it's used by mistake
|
582 | instead of `standardx`.
|
583 |
|
584 | ```bash
|
585 | npm uninstall standard
|
586 | ```
|
587 |
|
588 | ## What about Mocha, Jest, Jasmine, QUnit, etc?
|
589 |
|
590 | To support mocha in test files, add this to the top of the test files:
|
591 |
|
592 | ```js
|
593 | /* eslint-env mocha */
|
594 | ```
|
595 |
|
596 | Or, run:
|
597 |
|
598 | ```bash
|
599 | $ standard --env mocha
|
600 | ```
|
601 |
|
602 | Where `mocha` can be one of `jest`, `jasmine`, `qunit`, `phantomjs`, and so on. To see a
|
603 | full list, check ESLint's
|
604 | [specifying environments](http://eslint.org/docs/user-guide/configuring.html#specifying-environments)
|
605 | documentation. For a list of what globals are available for these environments,
|
606 | check the
|
607 | [globals](https://github.com/sindresorhus/globals/blob/master/globals.json) npm
|
608 | module.
|
609 |
|
610 | *Note: `env` and `envs` are equivalent.*
|
611 |
|
612 | ## What about Web Workers and Service Workers?
|
613 |
|
614 | Add this to the top of web worker files:
|
615 |
|
616 | ```js
|
617 | /* eslint-env worker */
|
618 | ```
|
619 |
|
620 | This lets `standard` (as well as humans reading the code) know that `self` is a
|
621 | global in web worker code.
|
622 |
|
623 | For Service workers, add this instead:
|
624 |
|
625 | ```js
|
626 | /* eslint-env serviceworker */
|
627 | ```
|
628 |
|
629 | ## Can I check code inside of Markdown or HTML files?
|
630 |
|
631 | To check code inside Markdown files, use [`standard-markdown`](https://www.npmjs.com/package/standard-markdown).
|
632 |
|
633 | Alternatively, there are ESLint plugins that can check code inside Markdown, HTML,
|
634 | and many other types of language files:
|
635 |
|
636 | To check code inside Markdown files, use an ESLint plugin:
|
637 |
|
638 | ```bash
|
639 | $ npm install eslint-plugin-markdown
|
640 | ```
|
641 |
|
642 | Then, to check JS that appears inside code blocks, run:
|
643 |
|
644 | ```bash
|
645 | $ standard --plugin markdown '**/*.md'
|
646 | ```
|
647 |
|
648 | To check code inside HTML files, use an ESLint plugin:
|
649 |
|
650 | ```bash
|
651 | $ npm install eslint-plugin-html
|
652 | ```
|
653 |
|
654 | Then, to check JS that appears inside `<script>` tags, run:
|
655 |
|
656 | ```bash
|
657 | $ standard --plugin html '**/*.html'
|
658 | ```
|
659 |
|
660 | ## Is there a Git `pre-commit` hook?
|
661 |
|
662 | Funny you should ask!
|
663 |
|
664 | ```bash
|
665 | #!/bin/bash
|
666 |
|
667 | # Ensure all JavaScript files staged for commit pass standard code style
|
668 | function xargs-r() {
|
669 | # Portable version of "xargs -r". The -r flag is a GNU extension that
|
670 | # prevents xargs from running if there are no input files.
|
671 | if IFS= read -r -d $'\n' path; then
|
672 | { echo "$path"; cat; } | xargs $@
|
673 | fi
|
674 | }
|
675 | git diff --name-only --cached --relative | grep '\.jsx\?$' | sed 's/[^[:alnum:]]/\\&/g' | xargs-r -E '' -t standard
|
676 | if [[ $? -ne 0 ]]; then
|
677 | echo 'JavaScript Standard Style errors were detected. Aborting commit.'
|
678 | exit 1
|
679 | fi
|
680 | ```
|
681 |
|
682 | ## How do I make the output all colorful and pretty?
|
683 |
|
684 | The built-in output is simple and straightforward, but if you like shiny things,
|
685 | install [snazzy](https://www.npmjs.com/package/snazzy):
|
686 |
|
687 | ```bash
|
688 | $ npm install snazzy
|
689 | ```
|
690 |
|
691 | And run:
|
692 |
|
693 | ```bash
|
694 | $ standard --verbose | snazzy
|
695 | ```
|
696 |
|
697 | There's also [standard-tap](https://www.npmjs.com/package/standard-tap),
|
698 | [standard-json](https://www.npmjs.com/package/standard-json),
|
699 | [standard-reporter](https://www.npmjs.com/package/standard-reporter), and
|
700 | [standard-summary](https://www.npmjs.com/package/standard-summary).
|
701 |
|
702 | ## Is there a Node.js API?
|
703 |
|
704 | Yes!
|
705 |
|
706 | ### `standard.lintText(text, [opts], callback)`
|
707 |
|
708 | Lint the provided source `text`. An `opts` object may be provided:
|
709 |
|
710 | ```js
|
711 | {
|
712 | cwd: '', // current working directory (default: process.cwd())
|
713 | filename: '', // path of the file containing the text being linted (optional, though some eslint plugins require it)
|
714 | fix: false, // automatically fix problems
|
715 | globals: [], // custom global variables to declare
|
716 | plugins: [], // custom eslint plugins
|
717 | envs: [], // custom eslint environment
|
718 | parser: '' // custom js parser (e.g. babel-eslint)
|
719 | }
|
720 | ```
|
721 |
|
722 | Additional options may be loaded from a `package.json` if it's found for the
|
723 | current working directory.
|
724 |
|
725 | The `callback` will be called with an `Error` and `results` object.
|
726 |
|
727 | The `results` object will contain the following properties:
|
728 |
|
729 | ```js
|
730 | var results = {
|
731 | results: [
|
732 | {
|
733 | filePath: '',
|
734 | messages: [
|
735 | { ruleId: '', message: '', line: 0, column: 0 }
|
736 | ],
|
737 | errorCount: 0,
|
738 | warningCount: 0,
|
739 | output: '' // fixed source code (only present with {fix: true} option)
|
740 | }
|
741 | ],
|
742 | errorCount: 0,
|
743 | warningCount: 0
|
744 | }
|
745 | ```
|
746 |
|
747 | ### `results = standard.lintTextSync(text, [opts])`
|
748 |
|
749 | Synchronous version of `standard.lintText()`. If an error occurs, an exception is
|
750 | thrown. Otherwise, a `results` object is returned.
|
751 |
|
752 | ### `standard.lintFiles(files, [opts], callback)`
|
753 |
|
754 | Lint the provided `files` globs. An `opts` object may be provided:
|
755 |
|
756 | ```js
|
757 | var opts = {
|
758 | ignore: [], // file globs to ignore (has sane defaults)
|
759 | cwd: '', // current working directory (default: process.cwd())
|
760 | fix: false, // automatically fix problems
|
761 | globals: [], // global variables to declare
|
762 | plugins: [], // eslint plugins
|
763 | envs: [], // eslint environment
|
764 | parser: '' // js parser (e.g. babel-eslint)
|
765 | }
|
766 | ```
|
767 |
|
768 | The `callback` will be called with an `Error` and `results` object (same as above).
|
769 |
|
770 | ## How do I contribute to StandardJS?
|
771 |
|
772 | Contributions are welcome! Check out the [issues](https://github.com/standard/standard/issues) or the [PRs](https://github.com/standard/standard/pulls), and make your own if you want something that you don't see there.
|
773 |
|
774 | Want to chat? Join contributors on IRC in the `#standard` channel on freenode.
|
775 |
|
776 | Here are some important packages in the `standard` ecosystem:
|
777 |
|
778 | - **[standard](https://github.com/standard/standard)** - this repo
|
779 | - **[standard-engine](https://github.com/standard/standard-engine)** - cli engine for arbitrary eslint rules
|
780 | - **[eslint-config-standard](https://github.com/standard/eslint-config-standard)** - eslint rules for standard
|
781 | - **[eslint-config-standard-jsx](https://github.com/standard/eslint-config-standard-jsx)** - eslint rules for standard (JSX)
|
782 | - **[eslint-plugin-standard](https://github.com/standard/eslint-plugin-standard)** - custom eslint rules for standard (not part of eslint core)
|
783 | - **[eslint](https://github.com/eslint/eslint)** - the linter that powers standard
|
784 | - **[snazzy](https://github.com/standard/snazzy)** - pretty terminal output for standard
|
785 | - **[standard-www](https://github.com/standard/standard-www)** - code for https://standardjs.com
|
786 | - **[semistandard](https://github.com/standard/semistandard)** - standard, with semicolons (if you must)
|
787 | - **[standardx](https://github.com/standard/standardx)** - standard, with custom tweaks
|
788 |
|
789 | There are also many **[editor plugins](#are-there-text-editor-plugins)**, a list of
|
790 | **[npm packages that use `standard`](https://github.com/standard/standard-packages)**,
|
791 | and an awesome list of
|
792 | **[packages in the `standard` ecosystem](https://github.com/standard/awesome-standard)**.
|
793 |
|
794 | ## Security Policies and Procedures
|
795 |
|
796 | The `standard` team and community take all security bugs in `standard` seriously. Please see our [security policies and procedures](https://github.com/standard/.github/blob/master/SECURITY.md) document to learn how to report issues.
|
797 |
|
798 | ## License
|
799 |
|
800 | [MIT](LICENSE). Copyright (c) [Feross Aboukhadijeh](https://feross.org).
|