The CommentSyntax linter enforces correct ERB comment syntax. It flags Ruby-style comments (<% # comment %>) which are technically invalid in ERB and can cause parsing failures, recommending the ERB-specific syntax (<%# comment %>) instead. Multi-line comments using standard Ruby syntax inside ERB tags are acceptable.

Bad ❌
<% # This is a Ruby comment %>
Good ✅
<%# This is an ERB comment %>

Good ✅
<%
  # This is a multi-line ERB comment.
%>

Caching is opt-in. To enable it, use the --cache option followed by the directory to cache.

• Enable cache: erb_lint --cache ./path/to/dir
• Custom cache directory: Use the --cache-dir option to specify a location other than the default .erb_lint_cache.
• Clear cache: Use the --clear-cache option to delete the existing cache directory.

Cached results store CachedOffense attributes necessary to restore results without re-running the full linting process. The cache automatically prunes outdated files during execution.

# Enable caching for the app directory
erb_lint --cache ./app

# Clear the cache
erb_lint --clear-cache

After creating a custom linter, enable it in your .erb_lint.yml file. You can then test it using the CLI with the --enable-linters flag and --lint-all to ensure it is running correctly.

# .erb_lint.yml
---
linters:
  CustomLinter:
    enabled: true
    custom_message: We suggest you change this file.

bundle exec erb_lint --enable-linters custom_linter --lint-all

You can suppress specific linting errors on a per-line basis by adding a disable comment to the offending line in your .erb file.

Format: <%# erb_lint:disable RuleName %>

Options:

• To report errors when a disable comment is present but does nothing, enable the NoUnusedDisable rule.
• To ignore all inline disable comments and report all offenses regardless, use the --disable-inline-configs CLI option.

<hr /> <%# erb_lint:disable SelfClosingTag %>

You can install erb_lint as a standalone gem or as a dependency in your application's Gemfile.

Requirements:

• Ruby 2.3.0 or higher (required for safe navigation operator &. and tilde-heredoc <<~ syntax).

gem install erb_lint

Or in your Gemfile

gem 'erb_lint', require: false

You can define a global list of files or patterns to exclude from linting by using the exclude key in your configuration. This list is automatically merged into the configuration of every individual linter, ensuring that excluded files are ignored across the entire suite.

Example configuration structure:

exclude:
  - "spec/**/*"
  - "vendor/**/*"

You can define exclusion patterns at two levels:

1. Global: Applies to all linters.
2. Linter-local: Applies only to a specific linter defined under the linters key.

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

Create a .erb_lint.yml file in your project root to customize linter behavior. While not mandatory (the tool works with defaults), a configuration file allows you to enable/disable linters and pass specific configurations to them.

Note: If you reference external configuration files (like .better-html.yml or .rubocop.yml), those files must exist, otherwise the tool will error.

---
EnableDefaultLinters: true
linters:
  ErbSafety:
    enabled: true
    better_html_config: .better-html.yml
  Rubocop:
    enabled: true
    rubocop_config:
      inherit_from:
        - .rubocop.yml

Enforces self-closing tag styles for void elements (e.g., area, br, img, input, link, etc.).

Options:

• enforced_style:
  • always (XHTML style): Requires <img />.
  • never (HTML5 style): Requires <img>.
  • Defaults to never.

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

Enforces a single space after <% and before %>. It ignores tags where the <% is followed by a newline or the %> is preceded by a newline.

---
linters:
  SpaceAroundErbTag:
    enabled: true

Prevents <script> tags from using type attributes that are not in an allowed whitelist. This helps prevent XSS vulnerabilities and typos.

Options:

• allowed_types: An array of allowed types. Defaults to ["text/javascript"].
• allow_blank: If false, <script> tags without a type attribute will be auto-corrected to <script type="text/javascript">. Defaults to true.
• disallow_inline_scripts: If true, prevents inline <script> tags anywhere in ERB templates. Defaults to false.

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