Managing Unused Function Parameters in ESLint with argsIgnorePattern

The default ESLint no-unused-vars rule often creates friction in functional programming patterns where parameters are required by an API signature but not used within a specific implementation. Instead of disabling the rule globally or polluting code with inline comments, you can use the argsIgnorePattern configuration to ignore specific parameters—typically those prefixed with an underscore.

By defining a regular expression for ignored arguments, you keep strict code quality for core logic variables while acknowledging intentional placeholder arguments in callbacks, middleware, or higher-order functions.

Configuring the Underscore Pattern

To implement this, modify the no-unused-vars rule in your ESLint configuration file (for example, .eslintrc.json or eslint.config.js). The most effective setup combines the underscore pattern with the args: 'after-used' setting to further reduce noise in functions with early returns or complex conditional logic.

{
  "rules": {
    "no-unused-vars": ["error", {
      "vars": "all",
      "args": "after-used",
      "argsIgnorePattern": "^_"
    }]
  }
}

Here, vars: "all" checks every variable declaration, args: "after-used" applies the after-used logic to arguments, and argsIgnorePattern: "^_" skips any parameter whose name starts with an underscore. These options are long-standing features of the core rule; confirm the exact schema against the rule documentation for your ESLint major version, since flat-config and legacy-config files express the same options differently.

Practical Example: Middleware and Callbacks

In the following example, an Express-style middleware requires the req and res objects, but this specific implementation only uses the response. Without the configuration above, ESLint would flag req as unused.

// The _req parameter is ignored because it starts with an underscore
const handleRequest = (_req, res, next) => {
  res.status(200).send("Success");
  next();
};

// This variable is still flagged because it is not ignored
const processData = (data) => {
  const timestamp = Date.now(); // Error: 'timestamp' is assigned but never used
  return data;
};

In processData, the timestamp variable still triggers an error because it does not match the underscore pattern. In handleRequest, _req is ignored because it matches argsIgnorePattern: '^_'.

Understanding the 'after-used' Strategy

The args option changes how ESLint evaluates argument usage. With the default "all", every declared argument is checked. With "after-used", only the arguments after the last one that is actually read are checked—so trailing unused parameters are reported, but leading unused ones before a used parameter are tolerated. This fits callback signatures where you must accept leading parameters to reach the one you need.

Limitations and Common Pitfalls

• Destructuring: argsIgnorePattern applies to the parameter name itself. If you destructure an object like ({ id, name }), an unused id is still flagged unless you rename the binding, for example ({ id: _id }).
• Rest and default parameters: The pattern only ignores matching parameter names; it does not suppress warnings for rest parameters, default-value bindings, or destructured variables that fail to match the regex.
• Over-reliance on 'after-used': This setting can mask genuinely unused trailing arguments in higher-order or callback patterns, and it can hide mistakes where a misspelled reference makes an argument appear used.

Verifying the Configuration

To verify the rule behaves as expected, create a small test file containing a function with an underscore-prefixed parameter and one genuinely unused variable, then run ESLint from your project root (no special permissions required):

npx eslint your-test-file.js

Confirm that no no-unused-vars warning is emitted for the underscore parameter, while the plain unused variable is still reported. If both are ignored or both are flagged, re-check that the options object is attached to the rule entry and that no other config file or inline comment overrides it. Before rolling this out across a repository, confirm the option schema on the official no-unused-vars documentation page for your installed ESLint version.