eslint-plugin-valtio

0.8.0 verified Sat Apr 25 auth: no javascript

ESLint plugin for Valtio that helps catch common mistakes when using proxy-based state management. Current version 0.8.0 supports both ESLint v8 (legacy config) and v9 (flat config). Key differentiators: specifically targets Valtio anti-patterns like stale snapshots in callbacks, mutating snapshots, using proxies in render phase, incorrect computed dependency order, and `this` usage in snapshots. Maintained by pmndrs. Release cadence: irregular updates with breaking changes in minor versions.

Common errors

error Cannot find module 'eslint-plugin-valtio' or 'valtio' module not found in extends ↓

cause Missing plugin installation or incorrect config path in .eslintrc.

fix

Run npm install --save-dev eslint-plugin-valtio. Ensure extends uses 'plugin:valtio/recommended'.

error ESLint: Invalid config: 'valtio/recommended' is not valid. ↓

cause Using the config string without 'plugin:' prefix in legacy config.

fix

Change to 'plugin:valtio/recommended' in extends array.

error TypeError: Cannot read properties of undefined (reading 'recommended') ↓

cause Using valtio.configs.recommended instead of valtio.configs['flat/recommended'] in flat config (v0.8.0+).

fix

Use valtio.configs['flat/recommended'] for ESLint v9 flat config.

Warnings

breaking v0.8.0: recommended config split into 'flat/recommended' (ESLint v9) and plugin:valtio/recommended (ESLint v8). Existing flat configs using valtio.configs['recommended'] will break. ↓

fix Use valtio.configs['flat/recommended'] with ESLint v9, or plugin:valtio/recommended with ESLint v8.

breaking v0.7.0: Added ESLint v9 flat config support with breaking changes in API exposure. Older configs may need migration. ↓

fix If using ESLint v9, use flat config pattern; for v8, stay on v0.6.x or use legacy extends string.

gotcha Plugin is CommonJS-only; attempting ESM import will fail with SyntaxError or import not found. ↓

fix Use require('eslint-plugin-valtio') instead of import.

Install

npm install eslint-plugin-valtio

yarn add eslint-plugin-valtio

pnpm add eslint-plugin-valtio

Imports

plugin default

wrong

import valtio from 'eslint-plugin-valtio'

correct

const valtio = require('eslint-plugin-valtio')

This plugin is CommonJS-only. ESM import will fail.

flat/recommended config (eslint v9)
wrong
```
valtio.configs.recommended
```
correct
```
valtio.configs['flat/recommended']
```
ESLint v9 uses flat config; the config key is 'flat/recommended' not 'recommended'.
recommended config (eslint v8)
wrong
```
valtio/recommended
```
correct
```
plugin:valtio/recommended
```
Legacy config uses extends string with 'plugin:' prefix.

Quickstart

Setup for ESLint v9 flat config and v8 legacy config with recommended rules.

// Install: npm install --save-dev eslint eslint-plugin-valtio

// For ESLint v9 (flat config) - eslint.config.js
const valtio = require('eslint-plugin-valtio');

module.exports = [
  valtio.configs['flat/recommended'],
  {
    rules: {
      'valtio/state-snapshot-rule': 'warn',
      'valtio/avoid-this-in-proxy': 'error',
    },
  },
];

// For ESLint v8 - .eslintrc.json
// { "extends": ["plugin:valtio/recommended"], "rules": { "valtio/state-snapshot-rule": "warn" } }