eslint-plugin-lookin-tavrus-plugin

An ESLint plugin for enforcing strict module boundaries in a Feature-Sliced Design architecture.

This plugin enforces consistent and maintainable import patterns in large-scale frontend applications using Feature-Sliced Design. It helps keep your code modular, scalable, and aligned with architectural rules by checking:

• ✅ Relative imports within the same slice
• ✅ Absolute imports allowed only via Public API (index.ts)
• ✅ Supports custom path aliases and test glob patterns

✨ Features

• ✅ Enforce Public API boundaries
• ✅ Enforce relative imports within the same slice
• ✅ Support for path aliases (e.g., @)
• ✅ Works with custom test file glob patterns
• ✅ Strictly scoped to key FSD layers: entities, features, pages, widgets

📦 Installation

npm install eslint-plugin-lookin-tavrus-plugin --save-dev

Make sure you also have ESLint installed:

npm install eslint --save-dev

⚙️ Usage

In your ESLint config:

// .eslintrc.js or similar
export default {
  plugins: ["lookin-tavrus-plugin"],
  rules: {
    "lookin-tavrus-plugin/public-api-imports": ["error", {
      alias: "@",
      testFilesPatterns: ["**/*.test.ts", "**/*.spec.ts", "**/StoreDecorator.tsx"]
    }],
    "lookin-tavrus-plugin/path-checker": ["error", {
      alias: "@"
    }]
  }
}

🔧 Rule Configuration

🔹 path-checker

Ensures relative imports within the same slice/module.

Useful to avoid deep imports like:

🚫 import { helper } from '@/features/user/model/slice/helper'

✅ Use relative instead:

import { helper } from '../../model/slice/helper'

Options

{
  alias?: string; // Optional path alias, e.g. "@"
}

🔹 public-api-imports

Restricts absolute imports to Public API (index.ts) and optionally allows testing.ts for test files.

Enforces:

• ✅ import { X } from '@/features/user' – ✔️ OK
• ❌ import { X } from '@/features/user/model/slice' – ❌ Not allowed
• ✅ import { X } from '@/features/user/testing' – ✔️ Only allowed in test files

Options

{
  alias?: string;
  testFilesPatterns?: string[]; // Glob patterns to match test files
}

📁 Recognized Layers

This plugin only applies import checks within these FSD layers:

• entities/
• features/
• widgets/
• pages/

Other folders like shared/ or app/ are not enforced by default.

📄 Example Project Structure

src/
├── entities/
│   └── comment/
│       ├── model/
│       ├── ui/
│       └── index.ts           <-- Public API
│       └── testing.ts   <-- Testing Public API
├── features/
│   └── user/
│       └── model/
│       └── index.ts

Correct Usage:

✅ import { useUser } from '@/features/user' ✅ import { getArticle } from '@/entities/article'

Incorrect Usage:

🚫 import { useUser } from '@/features/user/model/hooks' 🚫 import { helper } from 'features/user/model/helper'

✅ Valid & ❌ Invalid Examples

✅ Valid

// From same slice → relative
import { helper } from '../../model/helper'

// Public API import
import { UserCard } from '@/features/user'

// Testing import in test file
import { mockData } from '@/entities/user/testing'

❌ Invalid

// Deep import instead of Public API
import { helper } from 'features/user/model/helper'

// Absolute import within same slice
import { helper } from '@/features/user/model/helper'

// Testing import in non-test file
import { mockData } from '@/features/user/testing'

📄 Rule Summary

| Rule ID | Description | | ----------------------------------------- | --------------------------------------------------------- | | lookin-tavrus-plugin/path-checker | Enforces relative paths within the same slice | | lookin-tavrus-plugin/public-api-imports | Allows absolute imports only from Public API (index.ts) | | | Allows testing.ts imports only in test files |

👤 Author

Built with care by Aleksandr following the course of Ulbi TV to help frontend developers maintain modular, scalable projects using Feature-Sliced Design principles.