ESLint Plugin Literal Blacklist

1.2.0 verified Sat Apr 25 auth: no javascript

An ESLint micro plugin (v1.2.0) that allows you to define a blacklist of strings (string or regex) or objects with custom messages and ignoreCase option in literal expressions. No recent updates, simple rule set. Differentiators: lightweight, supports regex and custom messages per rule, minimal configuration.

Common errors

error ESLintError: Failed to load plugin 'literal-blacklist': Cannot find module 'eslint-plugin-literal-blacklist' ↓

cause Plugin not installed or installed as devDependency but not in right place.

fix

Run npm install eslint-plugin-literal-blacklist --save-dev from project root.

error Configuration for rule "literal-blacklist/literal-blacklist" is invalid: Severity should be one of the following: 0 = off, 1 = warn, 2 = error (you passed '"error"'). ↓

cause Using numeric severity as a string or vice versa in old ESLint versions.

fix

Use integer severity: [2, ['bad']] or standard ESLint expects either 0/1/2 or 'off'/'warn'/'error'. Some config parsers may be picky. Try: ['error', ['bad']].

error Error: Invalid term in literal-blacklist rule: expected a string or object with term property. ↓

cause Passed something other than string, RegExp, or object.

fix

Ensure each entry in the array is a string, a RegExp, or an object with a 'term' string property.

Warnings

gotcha Rule applies to all string literals, including in template literals and object property values, but not to comments or identifiers. ↓

fix Be aware that only literal expressions (AST Literal nodes) are checked; template literals with expressions are partially checked.

gotcha The ignoreCase option only works when you provide an object with { term: 'string' } — not with regex or plain strings. ↓

fix Use object form with 'ignoreCase: true' for case-insensitive matching of string terms. Regex already supports case-insensitive flags (/pattern/i).

gotcha Term objects with 'term' property must be strings; if you pass a regex as term it will be converted to string via toString, likely breaking. ↓

fix Use regex directly in the array, not inside an object's term property. Example: [2, [/bad/i]] works.

Install

npm install eslint-plugin-literal-blacklist

yarn add eslint-plugin-literal-blacklist

pnpm add eslint-plugin-literal-blacklist

Imports

default import of plugin

wrong

// Incorrect: missing quotes or wrong shape
module.exports = {
  plugins: [literal-blacklist], // ReferenceError
  rules: { 'literal-blacklist': [2, ['bad']] } // missing rule namespace
};

correct

module.exports = {
  plugins: ['literal-blacklist'],
  rules: { 'literal-blacklist/literal-blacklist': [2, ['bad']] }
};

The plugin registers as 'literal-blacklist' and the rule must be referenced as 'literal-blacklist/literal-blacklist'.

Rules in flat config (ESLint 9+)

wrong

// Wrong: using plugins array instead of object
import literalBlacklist from 'eslint-plugin-literal-blacklist';
export default [
  { plugins: [literalBlacklist], rules: { ... } } // breaks ESLint 9+
];

correct

import literalBlacklist from 'eslint-plugin-literal-blacklist';
export default [
  {
    plugins: { 'literal-blacklist': literalBlacklist },
    rules: { 'literal-blacklist/literal-blacklist': ['error', ['bad']] }
  }
];

ESLint flat config requires plugins to be an object with custom namespace. The plugin exports a single object, not an array.

Rule severity as string

wrong

"literal-blacklist/literal-blacklist": [2, ["bad"]] // numeric severity works but string is preferred in modern ESLint

correct

"literal-blacklist/literal-blacklist": ["error", ["bad"]]

Both numeric (0,1,2) and string ('off','warn','error') severity levels work. Only 'error' (or 2) will block build.

Quickstart

Shows installation and ESLint rule configuration with string, regex, and object with custom message and ignoreCase.

// Install: npm install eslint-plugin-literal-blacklist --save-dev
// .eslintrc.js
module.exports = {
  plugins: ['literal-blacklist'],
  rules: {
    'literal-blacklist/literal-blacklist': ['error', [
      'badword',
      /^secret_/,
      { term: 'password', message: 'Avoid using password literal', ignoreCase: true }
    ]]
  }
};