eslint-plugin-iblokz-style

iBlokz ESLint rules for style conventions that mainstream presets (prefer-const, Biome useConst) encode differently from how we write UI code.

Why this plugin exists

JavaScript const only forbids rebinding a name, not mutating a value. Mainstream linters treat “never reassigned” as “use const”, which pushes const subs = []; subs.push(...) — fine by spec, but not how we express intent.

Our convention separates two ideas:

• const — binding is fixed and the value is not mutated in place
• let — the binding’s value is built up or changed locally (.push, property writes, etc.)

State boundaries (e.g. iblokz-state patch) can still use immutable updates; these rules apply to local bindings inside functions and services.

Rules

prefer-const-bindings

Prefer const when a binding is never reassigned and never directly mutated.

Allow let when the binding is mutated in place — for example:

let subs = [];
subs.push(fromEvent(...));

This differs from core prefer-const, which only checks reassignment (=). That rule suggests const for let subs = []; subs.push(...), which conflicts with the iBlokz convention of using let for locally mutated collections and objects.

Direct mutations detected (v1):

• Mutating array methods: push, pop, shift, unshift, splice, sort, reverse, fill, copyWithin
• Mutating map/set methods: add, delete, clear, set
• Member assignment: obj.prop = value, arr[i] = value
• delete obj.prop
• Update expressions on members: arr.i++

Indirect mutation (e.g. mutate(arr)) is not detected.

no-mutate-const

Disallow direct mutation of const bindings.

const subs = [];
subs.push(x); // warn — use `let` if this collection grows in place

Pair with prefer-const-bindings for the full iBlokz convention:

| Pattern | Result | |---------|--------| | let + mutate | OK | | let + no mutate | prefer-const-bindings → use const | | const + mutate | no-mutate-const → use let or update immutably | | const + no mutate | OK |

Auto-fix (single declarator only): changes const to let at the declaration.

Install

pnpm add -D eslint eslint-plugin-iblokz-style

Usage

{
  "plugins": ["iblokz-style"],
  "rules": {
    "prefer-const": "off",
    "iblokz-style/prefer-const-bindings": "warn",
    "iblokz-style/no-mutate-const": "warn"
  }
}

Use alongside Biome:

• Disable Biome useConst — these rules replace it
• See iBlokz boilerplate linting docs for full toolchain setup (unused import/param policy, editor extensions, etc.)

Development

pnpm install
pnpm test
pnpm run lint

No build step — the package ships plain CommonJS source.

Releases

See CHANGELOG.md for version history.

Via CI (preferred)

1. Move [Unreleased] notes into a new version section in CHANGELOG.md and commit.
2. Bump and tag:

pnpm run release:patch   # or release:minor / release:major

That updates package.json, commits, tags v*, and pushes. The Release workflow then runs tests, creates a GitHub Release, and publishes to npm (NPM_TOKEN secret required).

Via local script

# After updating CHANGELOG and bumping version (e.g. pnpm version patch)
pnpm run publish:local

prepublishOnly runs tests and lint before publish. Prefer CI once the GitHub remote and NPM_TOKEN are set up.

License

MIT