eslint-plugin-neverthrow

1.1.4 verified Sat Apr 25 auth: no javascript

ESLint plugin enforcing that neverthrow Result types are handled. Current stable version is 1.1.4, released November 2021. It provides a single rule `must-use-result` that flags unhandled `Result` values from the neverthrow library. The plugin is TypeScript‑first, requires `@typescript-eslint/parser`, and relies on type information to detect unhandled results. Unlike manual lint rules, it integrates with ESLint's type‑aware analysis. No updates since 2021; the plugin is stable and low‑maintenance.

Common errors

error Error: Cannot find module '@typescript-eslint/parser' ↓

cause Missing required peer dependency @typescript-eslint/parser.

fix

npm install --save-dev @typescript-eslint/parser

error Error: Failed to load plugin 'neverthrow': Cannot find module 'eslint-plugin-neverthrow' ↓

cause Plugin not installed or ESLint cannot resolve it.

fix

npm install --save-dev eslint-plugin-neverthrow

error Definition for rule 'neverthrow/must-use-result' was not found ↓

cause Plugin not loaded in the config's 'plugins' array or misspelled rule name.

fix

Ensure plugins: ['neverthrow'] is present in config and rule is 'neverthrow/must-use-result' (lowercase).

Warnings

gotcha The plugin requires type information from TypeScript. Without setting 'parserOptions.project' pointing to a valid tsconfig.json, the rule will silently not work (no errors reported). ↓

fix Add 'parser: '@typescript-eslint/parser'' and 'parserOptions.project' pointing to your tsconfig.json.

gotcha The rule only works on synchronous code. Async/await with neverthrow Result is not detected (see issue #3). ↓

fix For async functions, manually handle the result or use a helper like .unwrapOr() within the async context.

deprecated As of v1.1.2, the plugin switched from using '@typescript-eslint/experimental-utils' to internal utilities to fix incompatibility with ESLint >=8. Ensure your ESLint version is >=5.16. ↓

fix Update to v1.1.2 or later if using ESLint 8. If on an older version, still upgrade to avoid shared type issues.

gotcha The plugin is not the official neverthrow plugin. It's community-maintained and has only one rule. For comprehensive handling, consider combining with other lint rules. ↓

fix Verify the plugin meets your needs; consider supplementing with manual checks or other plugins.

Install

npm install eslint-plugin-neverthrow

yarn add eslint-plugin-neverthrow

pnpm add eslint-plugin-neverthrow

Imports

eslint-plugin-neverthrow (plugin)
wrong
```
plugins: ['eslint-plugin-neverthrow']
```
correct
```
plugins: ['neverthrow']
```
ESLint automatically adds the 'eslint-plugin-' prefix. So the plugin name in config is just 'neverthrow'.
must-use-result rule
wrong
```
rules: { 'must-use-result': 'error' }
```
correct
```
rules: { 'neverthrow/must-use-result': 'error' }
```
Rules are always prefixed with the plugin name, e.g., 'neverthrow/rule-name'.
recommended config
wrong
```
extends: ['neverthrow/recommended']
```
correct
```
extends: ['plugin:neverthrow/recommended']
```
Full format is 'plugin:pluginName/configName'. Otherwise ESLint will look for an npm package 'eslint-config-neverthrow'.

Quickstart

Shows ESLint configuration to enforce handling neverthrow Result types and an example that triggers the rule.

// .eslintrc.js
module.exports = {
  plugins: ['neverthrow'],
  rules: {
    'neverthrow/must-use-result': 'error',
  },
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaVersion: 2021,
    sourceType: 'module',
    project: ['./tsconfig.json'],
    tsconfigRootDir: __dirname,
  },
};

// Example.ts
import { ok, err, Result } from 'neverthrow';

function compute(): Result<number, string> {
  return ok(42);
}

const result = compute(); // ❌ flagged: result not handled
type: 'typescript'