eslint-plugin-workspaces

0.12.1 verified Sat Apr 25 auth: no javascript

An ESLint plugin for enforcing consistent imports across monorepo packages. Current stable version is 0.12.1, released in March 2025, with active development. It supports npm, pnpm, yarn, bun, lerna, and bolt workspaces. Key differentiators include automatic workspace detection, fixable rules for no-relative-imports and no-absolute-imports, and presets for both flat config and eslintrc. It provides TypeScript definitions and requires eslint >=8.40.0. The recommended preset enforces rules like no-relative-imports and require-dependency to prevent cross-package import violations.

Common errors

error Error: Cannot find module 'eslint-plugin-workspaces' ↓

cause Package not installed as dev dependency.

fix

Run npm install -D eslint-plugin-workspaces.

error Configuration for rule "workspaces/no-relative-imports" is invalid: Value "error" is the wrong type. ↓

cause Using string severity in flat config without proper object syntax.

fix

Use object syntax: 'workspaces/no-relative-imports': 'error' is correct; ensure no extra wrapping.

error ESLint couldn't find the plugin "eslint-plugin-workspaces". ↓

cause Plugin not loaded in flat config or incorrect import.

fix

Import the default export: import workspaces from 'eslint-plugin-workspaces' and add to plugins.

Warnings

deprecated The presets 'flat/recommended' and 'flat/all' are deprecated since v0.12.0. ↓

fix Use 'recommended' and 'all' instead.

deprecated The 'scopes' configuration option is deprecated since v0.10.0. ↓

fix Remove scopes configuration; workspace detection is automatic.

breaking In v0.12.0, presets were migrated to flat config format. Legacy eslintrc format presets require 'legacy-' prefix. ↓

fix For eslintrc use 'plugin:workspaces/legacy-recommended' instead of 'plugin:workspaces/recommended'.

gotcha The plugin may not detect workspaces correctly if the package.json does not have a 'workspaces' field or if using an unsupported monorepo tool. ↓

fix Ensure your workspace configuration is supported (npm, pnpm, yarn, bun, lerna, bolt) and that the root package.json has a 'workspaces' array.

Install

npm install eslint-plugin-workspaces

yarn add eslint-plugin-workspaces

pnpm add eslint-plugin-workspaces

Imports

default
wrong
```
const workspaces = require('eslint-plugin-workspaces')
```
correct
```
import workspaces from 'eslint-plugin-workspaces'
```
ESM default import recommended for flat config; CommonJS require works but may lack TypeScript support

rules

wrong

const { rules } = require('eslint-plugin-workspaces')

correct

import { rules } from 'eslint-plugin-workspaces'

Named export for rules object; available in both ESM and CJS

configs

wrong

import { configs } from 'eslint-plugin-workspaces';
configs.recommended

correct

import workspaces from 'eslint-plugin-workspaces';
workspaces.configs.recommended

configs is a property of the default export, not a separate named export. Access via default import.

Quickstart

This shows how to set up eslint-plugin-workspaces with flat config using TypeScript, including the recommended preset and custom rule overrides.

import workspaces from 'eslint-plugin-workspaces';

export default [
  workspaces.configs.recommended,
  {
    rules: {
      'workspaces/no-relative-imports': 'error',
      'workspaces/require-dependency': 'warn',
    },
  },
];