erb_lint

ERB Lint

erb_lint is a tool to help lint your ERB or HTML files using the included linters or by writing your own.

Requirements

• Ruby 2.3.0+

• This is due to use of the safe navigation operator (&.)
• This is also due to the use of the tilde-heredoc ` [!TIP]

Creating an .erb_lint.yml config file is not mandatory; the tool works out of the box with default settings.

Please note that the two config files referenced in the examples above and below must exist, or you will get an error. (Of course, you can omit the two config file references (i.e. the better_html_config key, and the rubocop_config section.)

See below for linter-specific configuration options.

Usage

This gem provides a command-line interface which can be run like so:

1. Run erb_lint [options] if the gem is installed standalone.
2. Run bundle exec erb_lint [options] if the gem is installed as a Gemfile dependency for your app.

For example, erb_lint --lint-all --enable-all-linters will run all available linters on all ERB files in the current directory or its descendants (**/*.html{+*,}.erb).

If you want to change the glob & exclude that is used, you can configure it by adding it to your config file as follows:

---
glob: "**/*.{html,text,js}{+*,}.erb"
exclude:
  - '**/vendor/**/*'
  - '**/node_modules/**/*'
linters:
  ErbSafety:
    enabled: true
    better_html_config: .better-html.yml
  Rubocop:
    enabled: true
    rubocop_config:
      inherit_from:
        - .rubocop.yml

Make sure to add **/ to exclude patterns; it matches the target files' absolute paths.

Enable or disable default linters

EnableDefaultLinters: enables or disables default linters. Default linters are enabled by default.

Disable rule at offense-level

You can disable a rule by placing a disable comment in the following format:

Comment on offending lines

To raise an error when there is a useless disable comment, enable NoUnusedDisable.

To disable inline comments and report all offenses, set --disable-inline-configs option.

Exclude

You can specify the exclude patterns both of global and lint-local.

---
exclude:
  - '**/global-lib/**/*'
linters:
  ErbSafety:
    exclude:
      - '**/local-lib/**/*'

Linters

Allowed ✅

Example configuration:

```yaml
---
linters:
  ErbSafety:
    enabled: true
    better_html_config: .better-html.yml

…

yaml
---
linters:
  Rubocop:
    enabled: true
    rubocop_config:
      inherit_from:
        - .rubocop.yml
      Layout/InitialIndentation:
        Enabled: false
      Layout/LineLength:
        Enabled: false
      Layout/TrailingEmptyLines:
        Enabled: false
      Layout/TrailingWhitespace:
        Enabled: false
      Naming/FileName:
        Enabled: false
      Style/FrozenStringLiteralComment:
        Enabled: false
      Lint/UselessAssignment:
        Enabled: false
      Rails/OutputSafety:
        Enabled: false

…

Bad ❌

Good ✅

RightTrim

Trimming at the right of an ERB tag can be done with either =%> or -%>, this linter enforces one of these two styles.

Example configuration:

---
linters:
  RightTrim:
    enabled: true
    enforced_style: '-'

SpaceAroundErbTag

Enforce a single space after in the ERB source. This linter ignores opening ERB tags () that are preceded by a newline.

Bad ❌

Good ✅

Example configuration:

---
linters:
  SpaceAroundErbTag:
    enabled: true

…

erb
Bad ❌

Good ✅

Bad ❌

  alert(1)

Good ✅

The autocorrection rule adds // markers to the existing script, as this is the default behavior for javascript_tag. This can be disabled by changing the correction_style linter option from cdata to plain.

Example configuration:

---
linters:
  NoJavascriptTagHelper:
    enabled: true
    correction_style: 'plain'

RequireScriptNonce

This linter prevents the usage of HTML `

Good ✅

Bad ❌

alert(1)

Good ✅

alert(1)

Bad ❌

Good ✅

Bad ❌

Good ✅

### SelfClosingTag

This linter enforces self closing tag styles for void elements.

The void elements are `area`, `base`, `br`, `col`, `embed`, `hr`, `img`, `input`, `keygen`, `link`, `menuitem`, `meta`, `param`, `source`, `track`, and `wbr`.

If `enforced_style` is set to `always` (XHTML style):

```erb
Bad ❌

Good ✅

If enforced_style is set to never (HTML5 style):

Bad ❌

Good ✅

Example configuration:

---
linters:
  SelfClosingTag:
    enabled: true
    enforced_style: 'always'

AllowedScriptType

This linter prevent the addition of `

Good ✅

…

yaml

linters: AllowedScriptType: enabled: true allowed_types: - 'application/json' - 'text/javascript' - 'text/html' allow_blank: false disallow_inline_scripts: false

…

yaml

linters: HardCodedString: enabled: true corrector: path: path/to/corrector_file.rb name: I18nCorrector i18n_load_path: config/locales/en.yml

…

ruby class I18nCorrector attr_reader :node

def initialize(node, filename, i18n_load_path, range) end

def autocorrect(tag_start:, tag_end:) ->(corrector) do node end end end

### StrictLocals
This linter enforces the use of [strict locals](https://guides.rubyonrails.org/layouts_and_rendering.html#strict-locals) in Rails view partial templates.

app/views/foo/_bar.html.erb

Bad ❌

Good ✅

**Note**: This linter does not enforce the use of strict locals in view templates (files that don't start with `_`).  
**Note**: This linter does not prevent the use of instance variables. It merely enforces that a strict locals declaration is present. It's recommended to use this linter in conjunction with the `PartialInstanceVariable` linter to enforce the use of locals.

## CommentSyntax

This linter enforces the use of the correct ERB comment syntax, since Ruby comments (`` with a space) are not technically valid ERB comments.

```erb
Bad ❌

Good ✅

Bad ❌

Good ✅

Good ✅

Custom Linters

erb_lint allows you to create custom linters specific to your project. It will load linters from the .erb_linters directory in the root of your repository. See the linters directory for examples of how to write linters.

# .erb_linters/custom_linter.rb

module ERBLint
  module Linters
    class CustomLinter ` to match start of tag.
In file: app/views/subscriptions/index.html.erb:38

2 error(s) were found in ERB files

Compact

erb_lint --format compact
Linting 8 files with 12 linters...
app/views/users/show.html.erb:95:0: Remove multiple trailing newline at the end of the file.
app/views/users/_graph.html.erb:27:37: Extra space detected where there should be no space
2 error(s) were found in ERB files

JUnit

erb_lint --format junit

  
    
    
    
    
    
  
  
    
      
    
  
  

GitLab

Used by GitLab Code Quality.

[
   {
      "description":"Extra space detected where there should be no space.",
      "check_name":"SpaceInHtmlTag",
      "fingerprint":"5a259c7cafa2c9ca229dfd7d21536698",
      "severity":"info",
      "location":{
         "path":"app/views/subscriptions/_loader.html.erb",
         "lines":{
            "begin":1,
            "end":1
         }
      }
   },
   {
      "description":"Remove newline before `%\u003e` to match start of tag.",
      "check_name":"ClosingErbTagIndent",
      "fingerprint":"60b4ed2120c7abeebebb43fba4a19559",
      "severity":"warning",
      "location":{
         "path":"app/views/subscriptions/_loader.html.erb",
         "lines":{
            "begin":52,
            "end":54
         }
      }
   }
]

Caching

The cache is currently opt-in - to turn it on, use the --cache option:

erb_lint --cache ./app
Cache mode is on
Linting 413 files with 15 linters...
File names pruned from the cache will be logged

No errors were found in ERB files

Cached lint results are stored in the .erb_lint_cache directory by default, though a custom directory can be provided via the --cache-dir option. Cache filenames are computed with a hash of information about the file and erb_lint settings.

These files store instance attributes of the CachedOffense object, which only contain the Offense attributes necessary to restore the results of running erb_lint for output. The cache also automatically prunes outdated files each time it's run.

You can also use the --clear-cache option to delete the cache file directory.

License

This project is released under the MIT license.