Quick Start

This tutorial takes you from an empty project to a linted codebase with a committed configuration file and an npm script you can run in CI. It assumes CoffeeLint is installed as described in Installation.

Step 1: Lint a File with the Defaults

Create src/cart.coffee with a few deliberate problems:

class shoppingCart
  constructor: ->
    @items = []

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

Run CoffeeLint on the src directory:

coffeelint src

When given a directory, CoffeeLint recursively collects every *.coffee file in it (skipping node_modules). The output looks like this:

  ✗ src/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

Each line shows the severity symbol (✗ for errors, ⚡ for warnings), the line number, the rule's message, and optional context. The summary line counts errors, warnings, and files.

The three findings come from three default rules:

Line Rule Default level
1 camel_case_classes error
6 no_trailing_semicolons error
7 no_debugger warn

Step 2: Check the Exit Code

coffeelint src; echo "exit code: $?"
exit code: 1

The exit code is 1 whenever at least one error-level problem exists, and 0 otherwise. Warnings never fail the run. This is what makes CoffeeLint suitable for CI.

Step 3: Fix the Code

class ShoppingCart
  constructor: ->
    @items = []

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

Run the linter again:

coffeelint src
  ✓ src/cart.coffee

✓ Ok! » 0 errors and 0 warnings in 1 file

Step 4: Generate a Configuration File

CoffeeLint can print its complete default configuration. Save it as a starting point:

coffeelint --makeconfig > coffeelint.json

The file lists every built-in rule with its default level and options, for example:

{
  "indentation": {
    "value": 2,
    "level": "error"
  },
  "max_line_length": {
    "value": 80,
    "level": "error",
    "limitComments": true
  }
}

Because coffeelint.json sits at the project root, CoffeeLint finds it automatically for every file below it. No -f flag is needed.

Step 5: Customize the Rules

Suppose your team uses four-space indentation, allows 100-character lines, wants console.log calls flagged, and prefers spaces around operators. Edit coffeelint.json:

{
  "indentation": {
    "value": 4,
    "level": "error"
  },
  "max_line_length": {
    "value": 100,
    "level": "error",
    "limitComments": true
  },
  "no_debugger": {
    "level": "error",
    "console": true
  },
  "space_operators": {
    "level": "error"
  }
}

You do not need to keep every rule in the file. Any rule you leave out keeps its default settings.

Step 6: Trim the Configuration

A full --makeconfig dump is long and hides what you actually changed. Ask CoffeeLint for the minimal equivalent:

coffeelint --trimconfig

This compares your configuration with the defaults and prints only the settings that differ. Redirect it to a temporary file and replace your config with it to keep the file short and reviewable. (Write to a separate file first: redirecting straight into the file being read would truncate it before CoffeeLint reads it.)

coffeelint --trimconfig > coffeelint.min.json
mv coffeelint.min.json coffeelint.json

Step 7: Add an npm Script and Run It in CI

{
  "scripts": {
    "lint": "coffeelint src test"
  }
}

In CI, run npm run lint. The non-zero exit code on errors fails the build; warnings are printed but tolerated. To produce a machine-readable report for a CI dashboard, pick a reporter:

coffeelint --reporter checkstyle src > coffeelint-report.xml

Step 8: Silence a Rule Where It Makes Sense

Sometimes a rule is right in general but wrong for a specific line. Use an inline directive instead of weakening the whole configuration:

# coffeelint: disable=max_line_length
url = "https://example.com/a/very/long/path/that/cannot/reasonably/be/split/#{id}/details"
# coffeelint: enable=max_line_length

What You Learned

  • coffeelint <path> lints files and directories, and the exit code reflects error-level findings.
  • --makeconfig and --trimconfig bootstrap and tidy a coffeelint.json.
  • Configuration is discovered automatically from the project.
  • Inline directives handle justified exceptions.

Next Steps