ESLint Plugin Pinia

0.4.2 verified Sat Apr 25 auth: no javascript

An ESLint plugin that enforces best practices for writing Pinia stores in Vue.js applications. Current stable version is 0.4.2, released in November 2025, with a focus on store structure and common pitfalls. It provides a recommended configuration that includes rules like never-export-initialized-store, no-duplicate-store-ids, no-return-global-properties, and no-store-to-refs-in-store, plus optional rules like prefer-single-store-per-file. Ships TypeScript types, requires ESLint >=8.0.0 and @typescript-eslint/utils >=7.5, and supports both legacy ESLint config and flat config.

Common errors

error Error: Failed to load plugin 'pinia' declared in 'plugins': Cannot find module 'eslint-plugin-pinia' ↓

cause Missing npm install of eslint-plugin-pinia or incorrect plugin name in config.

fix

Run: npm install eslint-plugin-pinia --save-dev and ensure plugin name is 'pinia' (without 'eslint-plugin-') in legacy config.

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

cause Trying to access pinia.configs after require() in CJS, but package is ESM-only.

fix

Use dynamic import: const pinia = await import('eslint-plugin-pinia'); or switch to ESM.

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

cause Using pinia.configs['recommended'] in flat config; should be 'recommended-flat'.

fix

Replace pinia.configs['recommended'] with pinia.configs['recommended-flat'].

error Parsing error: 'defineStore' is not defined ↓

cause ESLint rule requires that defineStore is imported from 'pinia', but it's missing.

fix

Add import { defineStore } from 'pinia' to your store file.

Warnings

gotcha Flat config users must use 'recommended-flat' or 'all-flat' config keys, not 'recommended' or 'all'. ↓

fix Use pinia.configs["recommended-flat"] instead of pinia.configs["recommended"].

deprecated Legacy .eslintrc format (like 'extends': ['plugin:pinia/recommended']) is deprecated but still supported. ↓

fix Consider migrating to flat config (eslint.config.js) with pinia.configs["recommended-flat"].

gotcha The rule 'prefer-single-store-per-file' is disabled by default, but users may expect it to be active. ↓

fix Explicitly enable the rule if desired: "pinia/prefer-single-store-per-file": "warn".

breaking Requires ESLint >= 8.0.0 and Node >= 18. Older ESLint versions are not supported. ↓

fix Upgrade ESLint to 8.0.0 or higher, and Node to 18+.

gotcha Using storeToRefs inside a store definition is flagged by rule no-store-to-refs-in-store, which is in the recommended set. ↓

fix Remove storeToRefs calls from inside defineStore; use the store's reactive properties directly.

Install

npm install eslint-plugin-pinia

yarn add eslint-plugin-pinia

pnpm add eslint-plugin-pinia

Imports

default import (plugin object)
wrong
```
const pinia = require('eslint-plugin-pinia')
```
correct
```
import pinia from 'eslint-plugin-pinia'
```
ESM only; package has no default export in CJS. Use import for both flat and legacy configs.
recommended-flat config
wrong
```
pinia.configs["recommended"]
```
correct
```
pinia.configs["recommended-flat"]
```
In flat config, use 'recommended-flat' not 'recommended'. The 'recommended' key is for legacy .eslintrc.
all-flat config
wrong
```
pinia.configs["all"]
```
correct
```
pinia.configs["all-flat"]
```
In flat config, use 'all-flat'. The 'all' key is for legacy .eslintrc.

Quickstart

Shows how to import and configure the plugin in ESLint flat config, including rules and recommended preset.

import pinia from 'eslint-plugin-pinia';

export default [
  {
    plugins: {
      pinia
    },
    rules: {
      "pinia/no-duplicate-store-ids": "error",
      "pinia/no-store-to-refs-in-store": "error"
    }
  }
];

// Also use the recommended flat config:
export default [
  pinia.configs["recommended-flat"]
];