eslint-plugin-better-mutation

2.1.0 verified Sat Apr 25 auth: no javascript

ESLint plugin (v2.1.0) that controls where mutation is allowed in JavaScript/TypeScript, preventing unsafe reassignment of shared variables (globals, parameters, closed-over variables) while permitting safe mutation of locally declared variables. Designed for functional programming style, with support for flat config (ESLint >=9) and classic config. Differentiates from eslint-plugin-immutable by allowing local mutation and providing safer defaults. Active development, monthly releases, peer dep eslint >=6.

Common errors

error ESLint couldn't find the config "plugin:better-mutation/recommended". ↓

cause Using classic config string plugin name incorrectly or version mismatch.

fix

Ensure eslint-plugin-better-mutation is installed and in .eslintrc use the full string "plugin:better-mutation/recommended".

error Cannot find module 'eslint-plugin-better-mutation' ↓

cause Package not installed or not in node_modules.

fix

Run 'npm install --save-dev eslint-plugin-better-mutation' and verify it appears in package.json.

error Error: Cannot read properties of undefined (reading 'no-mutating-functions') ↓

cause Importing plugin incorrectly; the plugin object is not loaded as expected.

fix

Use the default import: 'import pluginBetterMutation from "eslint-plugin-better-mutation"'.

Warnings

gotcha The rule 'no-param-reassign' is NOT the same as this plugin; this plugin treats parameter reassignment as unsafe while allowing local variable mutation. ↓

fix Use eslint-plugin-better-mutation rules instead of core 'no-param-reassign' for FP-focused mutation control.

gotcha CommonJS module.exports assignment is allowed by default, but other global assignments are errors. This can be surprising if you expect all reassignment to be blocked. ↓

fix To block module.exports assignment, configure the rule with exemptedModuleExports: false.

gotcha Destructured properties are not considered safe for reassignment; the rule will flag '({ prop }) => { prop = 1; }' even though prop is a local copy. ↓

fix Avoid reassigning destructured parameters; treat them as read-only.

deprecated The 'recommended' config from this plugin is deprecated in favor of flat config's 'extends' approach. Use 'plugin:better-mutation/recommended' in classic config only. ↓

fix Migrate to flat config and reference configs.recommended.

Install

npm install eslint-plugin-better-mutation

yarn add eslint-plugin-better-mutation

pnpm add eslint-plugin-better-mutation

Imports

default
wrong
```
const pluginBetterMutation = require("eslint-plugin-better-mutation")
```
correct
```
import pluginBetterMutation from "eslint-plugin-better-mutation"
```
ESM default import. For CommonJS use require('eslint-plugin-better-mutation') in eslint.config.cjs. Flat config requires ESM.

rules

wrong

const rules = require("eslint-plugin-better-mutation").rules

correct

import { rules } from "eslint-plugin-better-mutation"

Named export for direct rule access. Not needed if using plugin object.

configs
```
import { configs } from "eslint-plugin-better-mutation"
```
Named export for configs; used in flat config. CommonJS: const { configs } = require('eslint-plugin-better-mutation').

Quickstart

Shows minimal ESLint flat config (ESM) with two mutation rules enabled.

import pluginBetterMutation from "eslint-plugin-better-mutation";
export default [
  {
    name: "my-project",
    plugins: {
      "better-mutation": pluginBetterMutation,
    },
    rules: {
      "better-mutation/no-mutating-functions": "error",
      "better-mutation/no-mutating-methods": "error",
    },
  },
];