Awesome

eslint-plugin-coffee

ESLint custom parser + rules for linting CoffeeScript source files

Table of Contents

• Getting Started
• Why does this project exist?
• How does eslint-plugin-coffee work?
• Can I use all of the existing ESLint plugins and rules without any changes?
• Installation
• Usage
• Usage with Prettier
• Supported Rules
  • ESLint-included rules
  • CoffeeScript-specific rules
  • eslint-plugin-react rules
  • eslint-plugin-import rules
  • eslint-plugin-react-native rules
  • eslint-plugin-jsx-a11y rules
• Supported CoffeeScript version
• Supported ESLint version
• Supported versions of eslint-plugin-react, eslint-plugin-import, eslint-plugin-react-native, eslint-plugin-jsx-a11y
• Migrating from CoffeeLint
• How can I help?
• License

Getting Started

The following sections will give you an overview of what this project is, why it exists and how it works.

If you are ready to get started you can jump to Installation.

Why does this project exist?

ESLint is the preeminent linter in the JavaScript world.

As of CoffeeScript v2.5.0, the CoffeeScript compiler exposes an Abstract Syntax Tree (AST) representation of your source code which enables usage with AST-based tools like ESLint.

eslint-plugin-coffee is the package that allows you to use ESLint in CoffeeScript-based projects :sparkles: :rainbow: :sparkles:

How does eslint-plugin-coffee work?

The AST (see above) produced by CoffeeScript is different than the AST format that ESLint requires to work.

This means that by default, the CoffeeScript AST is not compatible with the 1000s of rules which have been written by and for ESLint users over the many years the project has been going.

The great thing is, though, we can provide ESLint with an alternative parser to use - that is a first-class use case offered by ESLint. eslint-plugin-coffee provides ESLint with that alternative parser for CoffeeScript.

At that point, ESLint is capable of "digesting" CoffeeScript source code. But what about the rules? Keep reading...

Can I use all of the existing ESLint plugins and rules without any changes?

The short answer is, no.

The great news is, there are many rules which will "just work" without you having to change anything about them or provide any custom alternatives.

For rules which don't "just work" for CoffeeScript, eslint-plugin-coffee aims to provide a CoffeeScript-compatible custom alternative rule - this includes rules that come with ESLint, as well as from the popular ESLint plugins eslint-plugin-react, eslint-plugin-import, eslint-plugin-react-native, and eslint-plugin-jsx-a11y.

Here's a guide to all of the supported rules.

Installation

Make sure you have supported versions of CoffeeScript and ESLint installed and install the plugin:

yarn:

yarn add --dev coffeescript@^2.5.0 eslint@^6.0.0 eslint-plugin-coffee

npm:

npm install --save-dev coffeescript@^2.5.0 eslint@^6.0.0 eslint-plugin-coffee

Usage

Add eslint-plugin-coffee to the parser field and coffee to the plugins section of your .eslintrc configuration file, and disable ESLint rules that aren't compatible with CoffeeScript:

{
  "parser": "eslint-plugin-coffee",
  "plugins": ["coffee"],
  "extends": [
    "plugin/coffee:disable-incompatible"
  ]
}

Then configure the rules you want to use under the rules section.

{
  "parser": "eslint-plugin-coffee",
  "plugins": ["coffee"],
  "rules": {
    // Can include existing rules that "just work":
    "no-undef": "error",
    "react/no-array-index-key": "error",
    // ...CoffeeScript-specific rules:
    "coffee/spread-direction": ["error", "postfix"],
    // ...and CoffeeScript custom overriding rules.
    // For these, the corresponding existing rule should also be disabled if need be:
    "no-unused-vars": "off",
    "coffee/no-unused-vars": "error"
}

To apply eslint:recommended (the set of rules which are recommended for all projects by the ESLint team) with this plugin, add plugin:coffee/eslint-recommended (which will adjust the eslint:recommended config appropriately for CoffeeScript) to your config:

{
  "extends": [
    "plugin:coffee/eslint-recommended"
  ]
}

To apply the well-known Airbnb config with this plugin, add plugin:coffee/airbnb (for React projects) or plugin:coffee/airbnb-base (for non-React projects) to your config:

{
  "extends": [
    // for React projects:
    "plugin:coffee/airbnb",
    // OR for non-React projects:
    "plugin:coffee/airbnb-base"
  ],
  "rules": {
    // You may then want to disable some of the more "controversial" Airbnb rules
    // when applied to CoffeeScript, e.g.:
    "coffee/implicit-arrow-linebreak": "off",
    "coffee/comma-style": "off",
    "coffee/jsx-wrap-multilines": "off"
  }
}

eslint-plugin-import

If you want to use rules from eslint-plugin-import (whether rules that "just work" or CoffeeScript custom overrides), add plugin:coffee/import (which configures eslint-plugin-import to work with CoffeeScript) to your config, along with the rules you want to use:

{
  "extends": [
    "plugin:coffee/import"
  ],
  "rules": {
    // Can include existing rules that "just work":
    "import/no-unresolved": "error",
    // ...and CoffeeScript custom overriding rules.
    // For these, the corresponding existing rule should also be disabled if need be:
    "import/no-anonymous-default-export": "off",
    "coffee/no-anonymous-default-export": "error",
  }
}

See below for a list of all supported rules from eslint-plugin-import.

eslint-plugin-react, eslint-plugin-react-native, eslint-plugin-jsx-a11y

If you want to use rules from eslint-plugin-react, eslint-plugin-react-native and/or eslint-plugin-jsx-a11y (whether rules that "just work" or CoffeeScript custom overrides), add those plugins and rules to your config:

{
  "plugins": [
    "coffee",
    "react",
    "react-native",
    "jsx-a11y"
  ],
  "rules": {
    // Can include existing rules that "just work":
    "react/no-array-index-key": "error",
    "react-native/no-inline-styles": "error",
    "jsx-a11y/accessible-emoji": "error",
    // ...and CoffeeScript custom overriding rules.
    // For these, the corresponding existing rule should also be disabled if need be:
    "react/prop-types": "off",
    "coffee/prop-types": "error",
    "react-native/no-unused-styles": "off",
    "coffee/no-unused-styles": "error",
  }
} 

To apply the recommended config from eslint-plugin-react, add plugin:coffee/react-recommended to your config:

{
  "extends": [
    "plugin:coffee/react-recommended"
  ]
}

To apply the all config from eslint-plugin-react, add plugin:coffee/react-all to your config:

{
  "extends": [
    "plugin:coffee/react-all"
  ]
}

To apply the recommended config from eslint-plugin-jsx-a11y, add plugin:jsx-a11y/recommended to your config:

{
  "plugins: [
    "coffee",
    "jsx-a11y"
  ],
  "extends": [
    "plugin:jsx-a11y/recommended"
  ]
}

To apply the strict config from eslint-plugin-jsx-a11y, add plugin:jsx-a11y/strict to your config:

{
  "plugins: [
    "coffee",
    "jsx-a11y"
  ],
  "extends": [
    "plugin:jsx-a11y/strict"
  ]
}

See below for a list of all supported rules from eslint-plugin-react, eslint-plugin-react-native and eslint-plugin-jsx-a11y.

Running from the command line

To invoke ESLint from the command line, you can add an appropriate script to your package.json scripts section, for example:

{
  "scripts": {
    "lint": "eslint 'src/**/*.coffee'",
    "lint-fix": "eslint --fix 'src/**/*.coffee'"
  }
}

Then you can invoke those scripts as needed from the command line to lint the CoffeeScript source files in your project:

npm run lint

Running from your editor

Running ESLint directly from your code editor (e.g. on save) provides a quick feedback loop while developing.

Depending on your editor, there may or may not currently be a straightforward way to get ESLint running against .coffee files (e.g. using an ESLint editor plugin).

If you're having trouble getting ESLint running in your editor (and it's not listed below), please file an issue and we'll try and help with support for your editor.

VS Code

To run ESLint from VS Code, first install the VS Code ESLint extension.

Then add to your VS Code settings.json:

"eslint.validate": [
    // "javascript", "javascriptreact" is the default setting
    "javascript",
    "javascriptreact",
    {
        "language": "coffeescript",
        "autoFix": true
    },
]

Sublime Text

From @PatrickKing:

• Enable Package Control (if it is not already enabled).
• Enable CoffeeScript language support by installing Better CoffeeScript with Package Control (if it is not already installed).
• Install SublimeLinter and SublimeLinter-eslint with Package Control.
• Ensure eslint and eslint-plugin-coffee are installed locally with package.json or globally. (If globally, Try eslint some_file.coffee at your terminal to make sure.)
• Open "Preferences: SublimeLinter settings", and add/modify your user settings with:

"linters": {
    "eslint": {
        "selector": "source.js - meta.attribute-with-value, source.coffee"
    }
}

Other editors

We will add instructions for different code editors here as they become supported.

If you've gotten ESLint running in an editor not listed here and would like to share back, please file an issue!

Usage with Prettier

You can now use Prettier to format your CoffeeScript code, see the Prettier CoffeeScript plugin README for instructions.

To disable our code formatting related rules, install eslint-config-prettier:

npm install --save-dev eslint-config-prettier

Then use the prettier config exposed by this plugin:

{
  "extends": ["plugin:coffee/prettier"]
}

Alternatively, if you want to run Prettier as an ESLint rule (a nice option especially if you're running ESLint in fix mode via your editor):

npm install --save-dev eslint-config-prettier eslint-plugin-prettier

Then use the prettier-run-as-rule config exposed by this plugin:

{
  "extends": ["plugin:coffee/prettier-run-as-rule"]
}

Supported Rules

Key: :heavy_check_mark: = ESLint recommended, :wrench: = fixable

ESLint-included rules

Possible Errors

Best Practices

Node.js and CommonJS

Stylistic Issues

"ECMAScript 6"

CoffeeScript-specific rules

eslint-plugin-react rules

Key: :heavy_check_mark: = recommended, :wrench: = fixable

JSX-specific rules

eslint-plugin-import rules

Static analysis

Helpful warnings

Module systems

Style guide

eslint-plugin-react-native rules

eslint-plugin-jsx-a11y rules

Non-applicable ESLint-included rules

Some rules included with ESLint, eslint-plugin-react and eslint-plugin-import don't apply to CoffeeScript. These include:

• for-direction
• getter-return
• no-dupe-args
• no-extra-semi
• no-func-assign
• no-unexpected-multiline
• array-callback-return
• consistent-return
• curly
• eqeqeq
• no-case-declarations
• no-eq-null
• no-extra-label
• no-fallthrough
• no-implicit-globals
• no-labels
• no-lone-blocks
• no-octal
• no-octal-escape
• no-redeclare
• no-unused-labels
• no-void
• no-with
• require-await
• wrap-iife
• init-declarations
• no-label-var
• no-shadow-restricted-names
• no-undef-init
• no-undefined
• no-mixed-requires
• block-spacing
• brace-style
• func-call-spacing
• func-name-matching
• func-names
• func-style
• max-statements-per-line
• no-mixed-spaces-and-tabs
• no-nested-ternary
• no-ternary
• nonblock-statement-body-position
• object-curly-newline
• one-var
• one-var-declaration-per-line
• semi
• semi-spacing
• semi-style
• sort-vars
• space-before-blocks
• space-before-function-paren
• switch-colon-spacing
• template-tag-spacing
• arrow-body-style
• arrow-parens
• generator-star-spacing
• no-confusing-arrow
• no-const-assign
• no-var
• prefer-arrow-callback
• prefer-const
• require-yield
• yield-star-spacing
• no-multi-str
• react/require-render-return
• react/state-in-constructor
• import/no-mutable-exports

Supported CoffeeScript version

We will always endeavor to support the latest stable version of CoffeeScript.

The version range of CoffeeScript currently supported by this plugin is >=2.5.0.

Supported ESLint version

The version range of ESLint currently supported by this plugin is >=6.0.0.

Supported versions of eslint-plugin-react, eslint-plugin-import, eslint-plugin-react-native, eslint-plugin-jsx-a11y

The version range of eslint-plugin-react currently supported by this plugin is >=7.17.0.

The version range of eslint-plugin-import currently supported by this plugin is >=2.19.0.

The version range of eslint-plugin-react-native currently supported by this plugin is >=3.8.0.

The version range of eslint-plugin-jsx-a11y currently supported by this plugin is >=6.2.3.

Migrating from CoffeeLint

Here is a mapping from CoffeeLint rules to their corresponding ESLint rules:

If you haven't used ESLint before, you'll just need an .eslintrc config file in your project root - the Installation and Usage sections above cover how to get started. For further information, you may want to look at the official ESLint guide.

How can I help?

See an issue? Report it!

If you have the time and inclination, you can even take it a step further and submit a PR to improve the project.

License

eslint-plugin-coffee is licensed under the MIT License.