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