CoffeeLint is a style checker that helps keep CoffeeScript code clean and consistent. CoffeeScript does a great job at insulating programmers from many of JavaScript's bad parts, but it won't help enforce a consistent style across a code base. CoffeeLint can help with that.

If you have an idea, a bug report or anything else to say, reach out on the issues page.


To install, make sure you have a working version of the latest stable version of Node and NPM (the Node Package Manager) and then run:

npm install -g coffeelint

Leave off the g if you do not want to install globally.

Getting Started


Once you have Coffeelint installed, to lint your scripts, run:


To specify your own configuration file, do the following:

coffeelint -f coffeelint.json

If any errors were found, a non-zero code will be returned.

To generate a configuration file, do

coffeelint --makeconfig > coffeelint.json

You can then configure the rules to your liking.

New in 1.0: CoffeeLint will automatically pick up config files. When linting a file (as opposed to stdin) it will walk up the directory tree looking for a coffeelint.json or a package.json that has a "coffeelintConfig" object. If neither of those are found or you're linting from stdin it will check your home for a coffeelint.json file.


By default, CoffeeLint will help ensure you are writing idiomatic CoffeeScript, but every rule is optional and configurable so it can be tuned to fit your preferred coding style. To override any of CoffeeLint's default options, generate a configuration file and tweak it as needed. To enable an option, set its level to error, and to disable an option, set its level to ignore. If you set the level to warn, violations will be reported, but won't cause a non-zero exit code.

To disable a rule inline use the following:

# coffeelint: disable=max_line_length
foo = "some/huge/line/string/with/embed/#{values}.that/surpasses/the/max/column/width"
# coffeelint: enable=max_line_length

Here's a rundown of CoffeeLint's rules:

Name Description

This rule checks to see that there is spacing before and after the arrow operator that declares a function. This rule is disabled by default.

Note that if arrow_spacing is enabled, and you pass an empty function as a parameter, arrow_spacing will accept either a space or no space in-between the arrow operator and the parenthesis

# Both of this will not trigger an error,
# even with arrow_spacing enabled.
x(-> 3)
x( -> 3)

# However, this will trigger an error
x((a,b)-> 3)

default level: ignore

braces_spacing This rule checks to see that there is the proper spacing inside curly braces. The spacing amount is specified by "spaces". The spacing amount for empty objects is specified by "empty_object_spaces".

# Spaces is 0
{a: b}     # Good
{a: b }    # Bad
{ a: b}    # Bad
{ a: b }   # Bad

# Spaces is 1
{a: b}     # Bad
{a: b }    # Bad
{ a: b}    # Bad
{ a: b }   # Good
{ a: b  }  # Bad
{  a: b }  # Bad
{  a: b  } # Bad

# Empty Object Spaces is 0
{}         # Good
{ }        # Bad

# Empty Object Spaces is 1
{}         # Bad
{ }        # Good
This rule is disabled by default.

default level: ignore

camel_case_classes This rule mandates that all class names are UpperCamelCased. Camel casing class names is a generally accepted way of distinguishing constructor functions - which require the 'new' prefix to behave properly - from plain old functions.
# Good!
class BoaConstrictor

# Bad!
class boaConstrictor

This rule is enabled by default.

default level: error

coffeescript_error [no description provided]

default level: error


This rule checks to see that there is spacing before and after the colon in a colon assignment (i.e., classes, objects). The spacing amount is specified by spacing.left and spacing.right, respectively. A zero value means no spacing required.

# If spacing.left and spacing.right is 1

# Doesn't throw an error
object = {spacing : true}
class Dog
  canBark : true

# Throws an error
object = {spacing: true}
class Cat
  canBark: false

default level: ignore

cyclomatic_complexity Examine the complexity of your function.

default level: ignore

duplicate_key Prevents defining duplicate keys in object literals and classes

default level: error

empty_constructor_needs_parens Requires constructors with no parameters to include the parens

default level: ignore

ensure_comprehensions This rule makes sure that parentheses are around comprehensions.

default level: warn

eol_last Checks that the file ends with a single newline

default level: ignore

indentation This rule imposes a standard number of spaces to be used for indentation. Since whitespace is significant in CoffeeScript, it's critical that a project chooses a standard indentation format and stays consistent. Other roads lead to darkness.
Enabling this option will prevent this ugly
# but otherwise valid CoffeeScript.
twoSpaces = () ->
  fourSpaces = () ->
      eightSpaces = () ->
            'this is valid CoffeeScript'

Two space indentation is enabled by default.

default level: error

line_endings This rule ensures your project uses only windows or unix line endings. This rule is disabled by default.

default level: ignore

max_line_length This rule imposes a maximum line length on your code. Python's style guide does a good job explaining why you might want to limit the length of your lines, though this is a matter of taste. Lines can be no longer than eighty characters by default.

default level: error

missing_fat_arrows Warns when you use `this` inside a function that wasn't defined with a fat arrow. This rule does not apply to methods defined in a class, since they have `this` bound to the class instance (or the class itself, for class methods). The option `is_strict` is available for checking bindings of class methods. It is impossible to statically determine whether a function using `this` will be bound with the correct `this` value due to language features like `` and `Function.prototype.bind`, so this rule may produce false positives.

default level: ignore


Checks the number of newlines between classes and other code.

Options: -
- The number of required newlines after class definitions. Defaults to 3.

default level: ignore

no_backticks Backticks allow snippets of JavaScript to be embedded in CoffeeScript. While some folks consider backticks useful in a few niche circumstances, they should be avoided because so none of JavaScript's "bad parts", like with and eval, sneak into CoffeeScript. This rule is enabled by default.

default level: error

no_debugger This rule detects `debugger` and optionally `console` calls This rule is `warn` by default.

default level: warn

no_empty_functions Disallows declaring empty functions. The goal of this rule is that unintentional empty callbacks can be detected:
someFunctionWithCallback ->

The problem is that the call to doSomethingSignificant will be made regardless of someFunctionWithCallback's execution. It can be because you did not indent the call to doSomethingSignificant properly. If you really meant that someFunctionWithCallback should call a callback that does nothing, you can write your code this way:
someFunctionWithCallback ->

default level: ignore

no_empty_param_list This rule prohibits empty parameter lists in function definitions.
# The empty parameter list in here is unnecessary:
myFunction = () ->

# We might favor this instead:
myFunction = ->

Empty parameter lists are permitted by default.

default level: ignore

no_implicit_braces This rule prohibits implicit braces when declaring object literals. Implicit braces can make code more difficult to understand, especially when used in combination with optional parenthesis.
# Do you find this code ambiguous? Is it a
# function call with three arguments or four?
myFunction a, b, 1:2, 3:4

# While the same code written in a more
# explicit manner has no ambiguity.
myFunction(a, b, {1:2, 3:4})

Implicit braces are permitted by default, since their use is idiomatic CoffeeScript.

default level: ignore

no_implicit_parens This rule prohibits implicit parens on function calls.
# Some folks don't like this style of coding.
myFunction a, b, c

# And would rather it always be written like this:
myFunction(a, b, c)

Implicit parens are permitted by default, since their use is idiomatic CoffeeScript.

default level: ignore

no_interpolation_in_single_quotes This rule prohibits string interpolation in a single quoted string.
# String interpolation in single quotes is not allowed:
foo = '#{bar}'

# Double quotes is OK of course
foo = "#{bar}"

String interpolation in single quoted strings is permitted by default.

default level: ignore

no_nested_string_interpolation This rule warns about nested string interpolation, as it tends to make code harder to read and understand.
# Good!
str = "Book by #{firstName.toUpperCase()} #{lastName.toUpperCase()}"

# Bad!
str = "Book by #{"#{firstName} #{lastName}".toUpperCase()}"

default level: warn

no_plusplus This rule forbids the increment and decrement arithmetic operators. Some people believe the ++ and -- to be cryptic and the cause of bugs due to misunderstandings of their precedence rules. This rule is disabled by default.

default level: ignore

no_private_function_fat_arrows Warns when you use the fat arrow for a private function inside a class definition scope. It is not necessary and it does not do anything.

default level: warn

no_stand_alone_at This rule checks that no stand alone @ are in use, they are discouraged. Further information in CoffeeScript issue #1601

default level: ignore

no_tabs This rule forbids tabs in indentation. Enough said. It is enabled by default.

default level: error

no_this This rule prohibits 'this'. Use '@' instead.

default level: ignore

no_throwing_strings This rule forbids throwing string literals or interpolations. While JavaScript (and CoffeeScript by extension) allow any expression to be thrown, it is best to only throw Error objects, because they contain valuable debugging information like the stack trace. Because of JavaScript's dynamic nature, CoffeeLint cannot ensure you are always throwing instances of Error. It will only catch the simple but real case of throwing literal strings.
# CoffeeLint will catch this:
throw "i made a boo boo"

# ... but not this:
throw getSomeString()

This rule is enabled by default.

default level: error

no_trailing_semicolons This rule prohibits trailing semicolons, since they are needless cruft in CoffeeScript.
# This semicolon is meaningful.
x = '1234'; console.log(x)

# This semicolon is redundant.
alert('end of line');

Trailing semicolons are forbidden by default.

default level: error

no_trailing_whitespace This rule forbids trailing whitespace in your code, since it is needless cruft. It is enabled by default.

default level: error

no_unnecessary_double_quotes This rule prohibits double quotes unless string interpolation is used or the string contains single quotes.
# Double quotes are discouraged:
foo = "bar"

# Unless string interpolation is used:
foo = "#{bar}baz"

# Or they prevent cumbersome escaping:
foo = "I'm just following the 'rules'"

Double quotes are permitted by default.

default level: ignore

no_unnecessary_fat_arrows Disallows defining functions with fat arrows when `this` is not used within the function.

default level: warn

non_empty_constructor_needs_parens Requires constructors with parameters to include the parens

default level: ignore

prefer_english_operator This rule prohibits &&, ||, ==, != and !. Use and, or, is, isnt, and not instead. !! for converting to a boolean is ignored.

default level: ignore

space_operators This rule enforces that operators have spaces around them.

default level: ignore

spacing_after_comma This rule checks to make sure you have a space after commas.

default level: ignore

transform_messes_up_line_numbers This rule detects when changes are made by transform function, and warns that line numbers are probably incorrect.

default level: warn


If you'd like to run CoffeeScript in the browser or any other Javascript runtime, include coffee-script.js and coffeelint.js and you're off to the races. Then you can call CoffeeLint directly with the following API:

coffeelint.lint(source, configuration)

Lints the CoffeeScript source with the given configuration and returns an array of lint errors and warnings. If the array is empty, all is well. Compile time errors will be thrown. An error is a Javascript object with the following properties:

    rule :      'Name of the violated rule',
    lineNumber: 'Number of the line that caused the violation',
    level:      'The severity level of the violated rule',
    message:    'Information about the violated rule',
    context:    'Optional details about why the rule was violated'


Registers a custom rule that may be run by CoffeeLint. If the rule is ignored by default it will still require overriding it's level just like the default rules. They have actually all be re-implemented as pluggable rules that come bundled in CoffeeLint.

Loading Custom Rules

Not every possible rule will be included in the CoffeeLint project. Maybe it's very specific to your project, or it's not specific to CoffeeScript.

By convention rule authors add the keyword coffeelintrule to their npm package.json so custom rules can be found easily. Click here to list all currently available custom rules on npm.

For example, maybe you want to get a warning if you don't have a newline at the end of your files. We'll imagine you globally installed the package "coffeelint-newline-eof".

    // This name MUST match the default configuration of the rule being loaded.
    "newline_at_eof": {
        // NodeJS module to load. It can also be a path to the rule (useful for devleopment)
        "module": "coffeelint-newline-at-eof",
        // Maybe the rule author set it to error by default and you only want a warning.
        "level": "warn"

Now every time you run CoffeeLint it will load that rule and override it's default level to "warn".

Building Custom Rules

CoffeeLint has three types of linters that run. In no particular order they are.

Rules may be loaded using

--rules /path/to/rules/
when outside of the CLI.

Rules do not have to be written in CoffeeScript. A new instance of each rule is constructed for each file, so the RuleConstructor must be a constructor function that generates a new clean instance of your rule when the new operator is used.

Your rule instance must have a .rule attribute with it's default configuration. "name", "level" "message", and "description" are all required. "level" must be one of 'ignore', 'warn', or 'error'. Once you have a valid rule configuration CoffeeLint requires you to implement one function depending on which type of linter your rule needs. lintLine(line, lineApi)
lintToken(token, tokenApi)
lintNode(node, astApi)
The second parameter of each is an object with helper functions. It's best to just check the source or look at how other plugins are using those.

If your function returns true it will generate an error. If you need override how the error is generated, maybe providing a context attribute, you can return an object that will get mixed into the generated error. The NoPlusPlus is a simple example of this.

The core rules have been rewritten as stand alone rules both to prove the system and provide examples of how to write rules. To get started no_plus_plus is a Token rule, no_tabs is a Line rule, and cyclomatic_complexity is an AST rule.


option will load every .js or .coffee file it finds and assume they export the RuleConstructor. Since the browser doesn't have a standard export system it's up to you to determine how you'll load your plugin and register it with


Some nice folks have coded up some cool CoffeeLint plugins for editors and build systems. Check them out:


CoffeeLint is open sourced under the MIT License. If you want to hack on the code, report a bug or suggest a new feature, head on over here.

Thanks to CoffeeScript's developers for a great language (and a re-usable Lexer). Thanks to the creators of JSLint, JSHint, Pylint, lint and my mother for inspiration.

Change Log


- 2015.11.18

Most of the changes are more for linting the development files of coffeelint. The minor version increase is due to the change in cyclomatic_complexity, which now ignores nested functions. I foresee this change affecting very few people but probably still needs a minor version increase.

  • cyclomatic_complexity rule has been changed to ignore nested functions


- 2015.10.7

The v1.12.x versions are considered buggy and you should upgrade to v1.13.x if you experience problems

These releases were largely for bugfixes!
  • Bugfix for no_implicit_braces causing errors in classes and other edge cases
  • Bugfix for ensure_comprehensions where it failed if a nested loop had an equal sign
  • Bugfix for braces_spacing failing over generated curly braces
  • Several changes to indentation See bffa25 for the full list of changes. However between the release of v1.12.0 and v1.13.0, a regression was caused by fixing one of the indentation requests and as a result the change was reverted. The revert will most likely not affect too many users
  • Bugfix for newlines_after_classes, also fixed regressions caused between v1.12.0 and v1.13.0. If you have v1.12.x and are experiencing problems, please upgrade. Also note nested classes are now ignored completely
  • no_this is now compatible with no_stand_alone_at and will make checks against singular `this`
  • Bugfix for missing_fat_arrows, declaring a class prototype (via '::' operator) no longer fail if they don't use a fat arrow
  • Bugfix for eol_last, it now fails if there are multiple newlines at the end of a file (thanks charlierudolph)
  • Bugfix for arrow_spacing, now ignores arrow spacing in empty functions (thanks sgentle)


- 2015.8.19
  • New config option { "extends": "coffeelint-config-myconfig" } based on eslint's shareable configs
  • New rule no_nested_string_interpolation
  • New rule no_private_function_fat_arrows
  • New CLI option --ext to specify alternate file extensions to check
  • Bugfixes including tracking nested string interpolation which eleminates some misleading warnings


- 2015.5.31
  • New option --trimconfig. shows the minimal config to implement your customizations.
  • New rule eol_last
  • New rule no_this (prefer @ instead)
  • New option in no_debugger to flag console calls
  • Many small bug fixes


- 2015.5.5
  • Fix no_interpolation_in_single_quotes to only handle single quotes #400
  • Avoid non-standard String.prototype.trimRight #401
  • Strip comments from config file before parsing #407
  • missing_fat_arrows: fix constructor checking in strict mode #409
  • Use configfilter to expand module names


- 2015.4.6
  • missing_fat_arrows: added strict-mode option, defaults to false
  • Add "empty_object_spaces" to braces_spacing


- 2015.3.29
  • Add fat arrow to `arrow_spacing`
  • Fix an exception when package.json can't be parsed.


- 2015.2.22
  • Small change to make CoffeeLint compatible with


- 2015.2.20
  • Updated to CoffeeScript 1.9.1 thanks to swang
  • Fix no_implicit_braces error in class declarations
  • New rule braces_padding


- 2014.12.20
  • New rule ensure_comprehensions (warn by default)
  • Added options to transform code before processing it. (JSX support) or to use a different flavor of CoffeeScript .
  • New rule transform_messes_up_line_numbers. This simply tells you if a transform you're using changes the total number of lines in the file.


- 2014.12.15
  • Fix for spacing_after_comma so that newlines count as space after commas


- 2014.12.12
  • New rule spacing_after_comma
  • Indentation improvements
  • Fix Block RegExp triggering in no_unnecessary_double_quotes


- 2014.08.30
  • New rule prefer_english_operator
  • New behavior .coffeelintignore works just like a .gitignore
  • Exposed ErrorReporter to 3rd parties so reporters can be used outside our CLI implementation. See #330 for details
  • Linting from STDIN will look for config files.
  • -f option can specify a package.json that contains coffeelintConfig
  • Depricated --no-color in favor of new --color= option
  • Fixed an indentation bug when you have a blank line in the middle of a chained call.


- 2014.08.12
  • #317 Change $HOME search priority to account for non-default windows users.
  • #320 Remove support for chaining calls using a dot at the end of a line.
  • Removed extra messages that broke XML output.


- 2014.08.08
  • Indentation improvements for chained calls. See #285
  • Fixed some missing cases for space_operators
  • Fix for a last-line edge case in no_implicit_parens
  • Fixed trailing semicolons in multi-line strings with multiple embedded tokens


- 2014.06.07
  • #280 Fix for fat-arrow false positives. It was producing errors when the class is defined inside a function (AMD style)
  • MANY indentation fixes. See #282.


- 2014.05.28
  • New: --cache and coffeelint.setCache(obj)
  • Rule module loading is not limited to running from the commandline. See #279
  • Fix for #173: Empty functions surrounded by parens don't require spacing.
  • Fix for #271: trailing semicolons multiline strings are ignored
  • Fix for #214: no_unnecessary_fat_arrows doesn't trigger if the function contains super.


- 2014.05.16
  • Similar to grunt-cli, the coffeelint command will now load the project-specific version of coffeelint if there is one there.
  • 3rd party rules don't have to be globally installed any more.
  • Added --reporter option that also supports 3rd party reporters. coffeelint-stylish is the first one available.
  • Documentation for new users and 3rd party developers.


- 2014.04.17
  • New rule no_empty_functions
  • Improved documentation on how to contribute in
  • Rules using the AST work with a minified version of CoffeeScript
  • Fixed line length check to account for windows line endings


- 2014.03.07
  • New rule no_debugger
  • New rule no_interpolation_in_single_quotes
  • New rule no_unnecessary_double_quotes
  • Strict mode for no_implicit_parens. Turning it off allows implicit parens when they span multiple lines.


- 2014.02.22
  • CoffeeScript 1.7 support
  • Dropped support for CoffeeScript 1.6. (Use ~1.0.0 if you still need it)


- 2013.11.21
  • CoffeeLint will detect config files by default.
  • New rule colon_assignment_spacing
  • New rule no_unnecessary_fat_arrows
  • New rule missing_fat_arrows
  • Added an option to no_trailing_whitespace to forbid trailing space on empty lines
  • Added an option to no_implicit_braces to allow unambiguous implicit braces
  • Fixed --makeconfig
  • New option: --checkstyle
  • Fixed invalid XML produced by --jslint
  • Removed the need for the -r flag. It remains for backward compatibility but doesn't do anything now


- 2013.10.10
  • New internal structure to support custom rules.
  • Dropped support for NodeJS 0.6.


- 2013.08.10
  • CSVReporter now has a column for last line to account for cyclomatic complexity spanning the length of the function
  • Added support for literate CoffeeScript
  • Dropped support for CoffeeScript 1.4 and 1.5
  • Fixed non_empty_constructor_needs_parens for namespaced constructors
  • Simplified the build process to allow installing direct from the git repo
  • More fixes to indentation checking (continued
  • Fixed spacing error when returning negative numbers (
  • Fixed arrow spacing in callback parameters (
  • Added beginning and end line numbers for cyclomatic complexity (
  • Added header to CSVReporter
  • Fixes for space_operators(


- 2013.06.07
  • Added no_empty_param_list rule.
  • Added the --makeconfig option.
  • CoffeeScript 1.5 and 1.6 compatibility
  • Fixed indentation of chained functions. (, fixed 1/2 of #4)
  • Fixed bug in no_stand_alone_at (
  • Added arrow_spacing rule (require spaces around arrows)
  • Added empty_constructor_needs_parens
  • Added non_empty_constructor_needs_parens
  • Added duplicate_key (
  • Added no_trailing_whitespace.allowed_in_comments rule option (Allow trailing space in comments. Created to allow markdown)
  • Added newlines_after_classes rule
  • Line length exception. Lines containing only a link are ignored.


- 2012.11.06
  • Support for default configuration file using environment variable COFFEELINT_CONFIG.


- 2012.11.06
  • Added no_stand_alone_at rule.
  • Fixed correctly reporting line numbers of compilation errors after line 10.
  • Fixed incomplete results output.


- 2012.09.18


- 2012.09.15


- 2012.09.08


- 2012.04.06


- 2012.03.13


- 2012.01.26


- 2012.01.22
Fork me on GitHub