eslint-plugin-vitest-globals

1.6.1 verified Sat Apr 25 auth: no javascript

ESLint plugin that exposes all Vitest globals (describe, it, expect, vi, etc.) to ESLint without requiring an explicit eslint-plugin-vitest dependency. Current stable version is 1.6.1, released with support for ESLint 9+ Flat Config (flat/recommended, flat/base), TypeScript type definitions, and expanded globals including bench, benchmark, xtest, xit, xdescribe. Released as-needed with several minor bumps in 2023. Differentiators: lightweight (only handles globals), supports both classic and flat ESLint configs, and can be applied only to test files via overrides. Compatible with Node >=16.

Common errors

error ESLint: 'describe' is not defined. (no-undef) ↓

cause ESLint does not recognize Vitest globals without this plugin's configuration.

fix

Add the plugin to ESLint config (recommended or environment) as shown in quickstart.

error Failed to load config 'plugin:vitest-globals/recommended' from file... ↓

cause Plugin not installed or ESLint cannot resolve it.

fix

Run 'npm install -D eslint-plugin-vitest-globals' and ensure it's in package.json.

error Configuration for rule 'vitest-globals/...' not found ↓

cause Trying to use a rule from this plugin, but it exposes only globals, not rules.

fix

Use eslint-plugin-vitest for rules; this plugin only provides globals.

error Cannot find module 'eslint-plugin-vitest-globals' (ESLint 9 flat config) ↓

cause In flat config, the plugin import path may be incorrect or CJS/ESM mismatch.

fix

Use dynamic import or ensure your eslint.config.js uses ESM syntax with 'import vitestGlobals from 'eslint-plugin-vitest-globals';'

Warnings

breaking In v1.6.0, flat config keys changed from 'flat/recommended' to require the full 'flat/recommended' path; previously there was no flat support. ↓

fix Upgrade to v1.6.0+ and use vitestGlobals.configs['flat/recommended'].

gotcha This plugin only defines globals, it does not set up any rules. Users expecting rule enforcement must combine with eslint-plugin-vitest. ↓

fix Install eslint-plugin-vitest separately if you need Vitest-specific lint rules beyond globals.

deprecated Using env: { 'vitest-globals/env': true } is still supported but less explicit than using the recommended config. ↓

fix Prefer extending the recommended config or using the flat config approach.

gotcha The plugin must be applied to test files only; applying globally may cause false positives in non-test code using 'describe' or 'it' as variable names. ↓

fix Always use overrides or files filters to restrict the plugin to test file patterns.

breaking Node.js <16 is not supported as of v1.6.0 due to engine requirement. ↓

fix Upgrade Node.js to >=16 or pin to an older version of the plugin (not recommended).

Install

npm install eslint-plugin-vitest-globals

yarn add eslint-plugin-vitest-globals

pnpm add eslint-plugin-vitest-globals

Imports

plugin object (default import for flat config)
wrong
```
const vitestGlobals = require('eslint-plugin-vitest-globals')
```
correct
```
import vitestGlobals from 'eslint-plugin-vitest-globals'
```
For Flat Config (ESLint 9+), use ESM import. In CommonJS projects with ESLint 8, require() works but is not recommended for new code.
configs['flat/recommended']
wrong
```
vitestGlobals.configs.recommended
```
correct
```
vitestGlobals.configs['flat/recommended']
```
Flat config keys are named differently (prefixed with 'flat/') since v1.6.0. Classic config uses 'recommended' without prefix.
configs['recommended'] (Classic config)
wrong
```
"extends": ["plugin:vitest-globals/flat/recommended"]
```
correct
```
"extends": ["plugin:vitest-globals/recommended"]
```
In classic .eslintrc format, use 'plugin:vitest-globals/recommended'. Do not include 'flat/' prefix.

Quickstart

Configures ESLint to recognize Vitest globals only in test files, using either classic or flat config.

// Install: npm install -D eslint eslint-plugin-vitest-globals

// Classic .eslintrc.json (ESLint 8)
{
  "overrides": [
    {
      "files": ["**/__tests__/**/*.[jt]s?(x)", "**/*.test.[jt]s?(x)", "**/*.spec.[jt]s?(x)"],
      "extends": ["plugin:vitest-globals/recommended"]
    }
  ]
}

// Flat eslint.config.js (ESLint 9+)
import vitestGlobals from 'eslint-plugin-vitest-globals';
export default [
  {
    files: ['**/*.test.js', '**/*.spec.js'],
    ...vitestGlobals.configs['flat/recommended']
  }
];

// Now Vitest globals like describe, it, expect are recognized in test files.