Quick & dirty guide for using ESLint with Vim

Note: this assumes you have ESLint already set up with your Javascript project — including any extra plugins needed for React or another framework.

Installing and configuring the plugin

The easiest way to enable ESLint support in Vim is with using the syntastic plugin. The plugin’s README on Github has instructions for installing the plugin via the pathogen package manager, but for me, using Vundle, installation is as simple as adding this to my .vimrc:

Plugin 'scrooloose/syntastic'

And then running :PluginInstall.

Next, to configure the plugin, you’ll need to add a few lines to your .vimrc:

let g:syntastic_javascript_checkers = ['eslint']
let g:syntastic_always_populate_loc_list = 1
let g:syntastic_loc_list_height = 5
let g:syntastic_auto_loc_list = 0
let g:syntastic_check_on_open = 0
let g:syntastic_check_on_wq = 0

This configuration enables the ESLint syntax checker, will populate an error list in the location window (5 items high), but will not automatically open the error list. It does not check syntax on open, or at quitting, but it does check when saving.

These are my personal preferences, but there are many other options for configuration on the plugin’s README.

Using the plugin

With Syntastic and ESLint now configured, you will now start to see signifiers in Vim showing where you have errors (according to your .eslintrc). Here’s an example:

Syntastic signifiers in Vim

In the left gutter you see the highlighted “>>” symbol pointing to lines with errors. If you move the cursor to that line, you will see the error displayed in the Vim command line, like this:

Showing a single reported error

An underline is shown where errors occur as well. In the first screenshot above, you’ll see there’s an underline mark at the end of the first line with errors. That’s because we expect a semicolon there.

If you’d like to see all current errors in the current file, you can type :Errors in the Vim command line. The location list at the bottom of Vim will expand and look something like this:

Full error list from Syntastic

That’s it for the basic usage of Syntastic and ESLint in Vim. But below are a few extras for making this combination of plugins work even better.

Bonus tips

Using a local ESLint executable: If you use nvm to manage different Node versions per project, and don’t feel like installing ESLint globally, you can install the syntastic-local-eslint.vim plugin. Now, syntastic will look for a local ESLint executable (in ./node_modules/.bin/) before looking for a global version. No extra configuration is necessary.

Add to status bar: If you’d like the count of errors included in your Vim status bar, you can add the following to your statusline config:

set statusline+=\ %#warningmsg#
set statusline+=%{exists('g:loaded_syntastic_plugin')?SyntasticStatuslineFlag():''}
set statusline+=%*

And the display of that will look something like this (see right side):

Syntastic message in status line

Debugging: If for some reason you aren’t getting the errors showing up in Vim, you can run a few commands to enable debugging messages. With a Javascript file in the buffer, type the following in the Vim command line:

:let g:syntastic_debug=3
:SyntasticCheck eslint
:mes

Upon typing :mes, you should be shown any debug output from syntastic with (hopefully) a message about what went wrong, like “eslint executable not found.”

Getting fancy: If you would like to get a little more expressive with your gutter error signifiers, Alex Young at usevim has a good explanation on how to add fancier graphics. The video is also a better, and more in-depth look at getting Syntastic and ESLint working with Vim. And don’t miss out on the rest of the excellent tutorials and tips on the site.