CoffeeLint

CoffeeLint is a style checker and linter for CoffeeScript. It reads .coffee (and Literate CoffeeScript) source files, runs them through a configurable set of rules, and reports problems such as inconsistent indentation, trailing semicolons, overly long lines, misused fat arrows, duplicate object keys, and leftover debugger statements. It ships as a command-line tool, a Node.js library, and a browser bundle, so the same rules can run in your editor, your build, and your CI pipeline.

This documentation covers CoffeeLint 2.1.0, the final version in the clutchski/coffeelint repository.

Note: The upstream README states that CoffeeLint is no longer maintained, although the code remains freely available under the MIT license. The last commit in the repository dates from October 2021. Everything described here works as documented, but you should not expect new releases or bug fixes from this repository.

Why a Linter for CoffeeScript?

CoffeeScript is whitespace-sensitive and leans heavily on optional syntax: parentheses on function calls, braces on object literals, and return statements are all optional. That flexibility makes it pleasant to write, but it also means two developers can write the same logic in visibly different ways, and some mistakes compile without complaint. Two examples:

  • A callback that is accidentally not indented compiles into an empty function followed by a statement that always runs.
  • A function that uses this but was defined with a thin arrow (->) silently loses its binding when passed as a callback.

CoffeeLint catches these issues statically, before the code runs, and enforces a consistent house style so that code reviews can focus on behavior instead of formatting.

Key Features

  • 37 built-in rules covering whitespace, formatting, naming, syntax preferences, function binding, complexity, and likely bugs. See the Rules Overview.
  • Three severity levels per rule: error (fails the run), warn (reported but does not change the exit code), and ignore (rule disabled).
  • Automatic configuration discovery from a coffeelint.json, a coffeelintConfig section in package.json, a file named by the COFFEELINT_CONFIG environment variable, or a coffeelint.json in your home directory. See Configuration.
  • Inline directives such as # coffeelint: disable=max_line_length and the # noqa shortcut to silence rules for a block or a single line. See Inline Directives.
  • Multiple output formats: a human-friendly default reporter plus csv, jslint XML, checkstyle XML, and raw JSON for tooling. See Reporters.
  • Extensibility: write your own rules (token, line, or AST based), load them from npm packages or local files, plug in custom reporters, and preprocess source with transforms. See Writing Custom Rules.
  • A JavaScript API usable from Node.js build tools or directly in the browser. See the API Reference.
  • Literate CoffeeScript support for .litcoffee and .coffee.md files.
  • Result caching with --cache to speed up repeated runs on large codebases.

A Quick Taste

Given a file cart.coffee:

class shoppingCart
  constructor: ->
    @items = []

  add: (item) ->
    @items.push(item);
    debugger

Running the linter:

coffeelint cart.coffee

produces a report similar to:

  ✗ cart.coffee
     ✗ #1: Class name should be UpperCamelCased. class name: shoppingCart.
     ✗ #6: Line contains a trailing semicolon.
     ⚡ #7: Found debugging code. found 'STATEMENT'.

✗ Lint! » 2 errors and 1 warning in 1 file

The process exits with status 1 because at least one error-level problem was found. Warnings alone never change the exit code.

How CoffeeLint Works

Every file goes through three analysis passes, each powered by the CoffeeScript compiler itself:

  1. AST pass: the source is parsed into an abstract syntax tree. Syntax errors are reported here (as the coffeescript_error rule) and structural rules such as cyclomatic_complexity and missing_fat_arrows run.
  2. Lexical pass: the source is tokenized, and token-based rules such as space_operators, camel_case_classes, and no_plusplus inspect individual tokens.
  3. Line pass: each raw line is checked by line-based rules such as max_line_length, no_trailing_whitespace, and no_trailing_semicolons, with access to the tokens on that line.

Results are merged, sorted by line number, and filtered through any inline directives. The Architecture page explains this pipeline in detail.

When to Use CoffeeLint

  • You maintain a CoffeeScript codebase and want consistent formatting across contributors.
  • You want CI to fail on real problems (syntax errors, duplicate keys, thrown strings) while only warning on style preferences.
  • You build editor or build-tool integrations and need machine-readable lint output (CSV, XML, or JSON).
  • You want to enforce project-specific conventions with custom rules.

When It May Not Fit

  • New projects: because the tool is unmaintained, new projects should weigh that against their needs before adopting it.
  • CoffeeScript dialects: support for alternative compilers such as IcedCoffeeScript exists but is described by the project itself as basically unsupported. See Transforms and CoffeeScript Flavors.
  • Semantic analysis: CoffeeLint is a style and pattern checker. It does not perform type checking or detect undefined variables out of the box.

Where to Go Next