eslint-plugin-erb

2.1.1 verified Fri May 01 auth: no javascript

ESLint plugin to lint JavaScript inside ERB files (.js.erb) and optionally HTML inside .html.erb using html-eslint. Version 2.1.1 is current, actively maintained with monthly releases. Key differentiator: zero-dependency, supports ESLint flat config (v9+), handles ERB tags (<% %>, <%= %>) inside JS code, and provides recommended configs. Unlike generic processors, it also fixes autofix interactions with stylistic rules (e.g., quotes). The plugin requires explicitly disabling `reportUnusedDisableDirectives` to avoid false positives.

Common errors

error Error: ESLint configuration in eslint.config.js is invalid: - Unexpected top-level property "linterOptions" ↓

cause reportUnusedDisableDirectives is placed outside the object where it belongs.

fix

Wrap linterOptions inside a configuration object: { linterOptions: { reportUnusedDisableDirectives: 'off' } }.

error Error: Cannot find module 'eslint-plugin-erb' ↓

cause Package not installed or mismatched ESLint version (v2+ requires ESLint v9+).

fix

Install with npm install --save-dev eslint-plugin-erb and ensure ESLint is v9+.

error SyntaxError: Unexpected token '<' ↓

cause ESLint is trying to parse the entire .js.erb file as JavaScript without the processor, failing on ERB tags like <%%=.

fix

Add processor: erb.processors.processorJs to your config or use erb.configs.recommended.

Warnings

breaking v2.0.0 drops support for ESLint flat config migration: requires ESLint v9+ and eslint.config.js format. ↓

fix Use erb.configs.recommended in flat config, or switch to erb.configs['recommended-legacy'] for .eslintrc.*.

deprecated Legacy .eslintrc.* config format is deprecated in v2.0.0; recommended-legacy config is provided but will be removed in a future major version. ↓

fix Migrate to flat config (eslint.config.js) and use erb.configs.recommended.

gotcha Must set reportUnusedDisableDirectives to 'off' in linterOptions, otherwise ESLint will incorrectly warn about unused disable directives due to ERB tag transformation. ↓

fix Add `linterOptions: { reportUnusedDisableDirectives: 'off' }` to your ESLint config.

gotcha If using ESLint v9+, the flat config is required; .eslintrc.* files are not supported unless you use the legacy config via erb.configs['recommended-legacy']. ↓

fix Either use eslint.config.js with erb.configs.recommended or downgrade to v1.x.

Install

npm install eslint-plugin-erb

yarn add eslint-plugin-erb

pnpm add eslint-plugin-erb

Imports

default import
wrong
```
const erb = require('eslint-plugin-erb')
```
correct
```
import erb from 'eslint-plugin-erb'
```
ESM-only since v2 (supports ESLint flat config). CJS require() will fail.

erb.processors.processorJs

wrong

import { processorJs } from 'eslint-plugin-erb'

correct

import { processors } from 'eslint-plugin-erb';
const processorJs = erb.processors.processorJs;

processorJs is not a named export; access via erb.processors.processorJs.

erb.configs.recommended

wrong

import { erb } from 'eslint-plugin-erb'

correct

import erb from 'eslint-plugin-erb';
export default [ erb.configs.recommended, ... ]

Default export is the plugin object; use erb.configs.recommended, not { erb }.

erb.configs['recommended-legacy']
wrong
```
require('eslint-plugin-erb').configs['recommended-legacy']
```
correct
```
import erb from 'eslint-plugin-erb';  module.exports = [ erb.configs['recommended-legacy'] ];
```
For .eslintrc.js files (legacy format), use 'recommended-legacy' config. v2.0.0+ drops legacy support; this config is a backward-compatible alias.

Quickstart

Set up ESLint with eslint-plugin-erb using flat config and lint a .js.erb file, showing how ERB tags are ignored.

// 1. Install: npm install --save-dev eslint eslint-plugin-erb
// 2. Create eslint.config.js:
import erb from 'eslint-plugin-erb';
export default [
  erb.configs.recommended,
  {
    linterOptions: {
      reportUnusedDisableDirectives: 'off'
    }
  }
];
// 3. Lint your .js.erb file
// sample.js.erb:
const x = <%= some_ruby %>;
console.log(x);
// Run: npx eslint sample.js.erb
// This will lint the JS parts, ignoring ERB tags.
// The plugin will process the file and report any JS errors.