🚀 eslint-plugin-fsd-lint 🚀


English | 한국어

> It supports ESLint 9+ and the new Flat Config system.

📖 Introduction

eslint-plugin-fsd-lint is an ESLint plugin that enforces best practices for Feature-Sliced Design (FSD) architecture.

It is fully compatible with ESLint 9+ and follows the modern Flat Config format, ensuring seamless integration into modern JavaScript and TypeScript projects.

$3

- Flat Config support: Fully compatible with ESLint 9+ and the new Flat Config system.
- Strict FSD compliance: Prevents architectural violations in feature-based project structures.
- Improves maintainability: Encourages clear module separation and dependency control.
- Ensures consistent code quality: Standardizes import patterns and best practices.
- Cross-platform compatibility: Works seamlessly on both Windows and Unix-based systems.
- Flexible folder naming: Supports custom folder naming patterns (e.g., 1_app, 2_pages).
- Multiple alias formats: Supports both @shared and @/shared import styles.
- Comprehensive test coverage: Thoroughly tested with real-world scenarios and edge cases.

$3

Feature-Sliced Design (FSD) is a modern architecture pattern that provides a structured approach to organizing frontend applications.

This plugin enforces key FSD principles such as proper layer separation, import restrictions, and dependency management,
helping developers build scalable and maintainable codebases.

---

📦 Installation

You can install eslint-plugin-fsd-lint via npm or pnpm:

$3

``shell
npm install --save-dev eslint-plugin-fsd-lint
`

$3

`shell
pnpm add -D eslint-plugin-fsd-lint
`

$3

This plugin requires ESLint 9+ to work properly.

Make sure you have ESLint installed in your project:

`shell
npm install --save-dev eslint
`

> 💡 Tip: If you're using a monorepo with multiple packages, install eslint-plugin-fsd-lint at the root level to share the configuration across all workspaces.

---

🚀 Usage & Configuration

$3

eslint-plugin-fsd-lint is designed for ESLint 9+ and works seamlessly with the Flat Config system.

To use it in your project, add the following configuration to your eslint.config.mjs:

`js
import fsdPlugin from 'eslint-plugin-fsd-lint';

export default [
// Use the recommended preset
fsdPlugin.configs.recommended,

// Or configure rules individually
{
plugins: {
fsd: fsdPlugin,
},
rules: {
// Enforces FSD layer import rules (e.g., features cannot import pages)
'fsd/forbidden-imports': 'error',

// Disallows relative imports between slices/layers, use aliases (@)
// Allows relative imports within the same slice by default (configurable)
'fsd/no-relative-imports': 'error',

// Enforces importing only via public API (index files)
'fsd/no-public-api-sidestep': 'error',

// Prevents direct imports between slices in the same layer
'fsd/no-cross-slice-dependency': 'error',

// Prevents UI imports in business logic layers (e.g., entities)
'fsd/no-ui-in-business-logic': 'error',

// Forbids direct import of the global store
'fsd/no-global-store-imports': 'error',

// Enforces import order based on FSD layers
'fsd/ordered-imports': 'warn',
},
},
];
`

Key Principles Enforced by Default:

- Layered Imports: Higher layers cannot import from lower layers (e.g., features cannot import pages).
- Slice Isolation: Slices within the same layer should not directly import each other (no-cross-slice-dependency).
- Public API Usage: Imports from other slices/layers must go through their public API (index.js or index.ts). Direct internal imports are forbidden (no-public-api-sidestep).
- Absolute Paths (Aliases): Use absolute paths (configured via aliases like @) for imports between different slices or layers. Relative paths are generally disallowed (no-relative-imports).
- Relative Paths within Slices: Relative paths are allowed for imports _within the same slice_ (e.g., importing a helper from ../lib inside a feature). This is configurable via the allowSameSlice option in no-relative-imports (default: true).

$3

The plugin provides three pre-defined configurations for different strictness levels:

`js
import fsdPlugin from 'eslint-plugin-fsd-lint';

export default [
// Standard recommended configuration
fsdPlugin.configs.recommended,

// Strict configuration (all rules as error)
// fsdPlugin.configs.strict,

// Base configuration (less strict)
// fsdPlugin.configs.base,
];
`

$3

You can customize the behavior of the rules with advanced options:

`js
import fsdPlugin from 'eslint-plugin-fsd-lint';

export default [
{
plugins: {
fsd: fsdPlugin,
},
rules: {
// Configure alias format and folder patterns
'fsd/forbidden-imports': [
'error',
{
// Support for @shared or @/shared import styles
alias: {
value: '@',
withSlash: false, // Use true for @/shared format
},
// Support for numbered folder prefixes
folderPattern: {
enabled: true,
regex: '^(\\d+_)?(.*)',
extractionGroup: 2,
},
},
],

// Other rules...
},
},
];
`

$3

Here's how an FSD-compliant project might look:

`plaintext
src/
├── app/ (or 1_app/)
│ ├── providers/
│ ├── store.js
│ ├── index.js // Public API for app
│
├── processes/ (or 2_processes/)
│ ├── auth/
│ ├── onboarding/
│
├── pages/ (or 3_pages/)
│ ├── HomePage/
│ │ ├── ui/ // UI components for HomePage
│ │ └── index.ts // Public API for HomePage
│ ├── ProfilePage/
│
├── widgets/ (or 4_widgets/)
│ ├── Navbar/
│ │ ├── ui/
│ │ └── index.ts // Public API for Navbar
│ ├── Sidebar/
│
├── features/ (or 5_features/)
│ ├── login/
│ │ ├── ui/ // UI components for login feature
│ │ ├── model/ // Business logic for login
│ │ └── index.ts // Public API for login feature
│ ├── registration/
│
├── entities/ (or 6_entities/)
│ ├── user/
│ │ ├── ui/
│ │ ├── model/
│ │ └── index.ts // Public API for user entity
│ ├── post/
│
├── shared/ (or 7_shared/)
│ ├── ui/ // Reusable UI components
│ │ └── Button/ // Example: Button component
│ ├── lib/ // Utility functions, helpers
│ ├── config/ // Shared configuration
│ └── index.ts // Public API for shared layer (optional)

`

Import Examples based on Structure:

- Allowed (Alias Import - Cross Slice/Layer):
`javascript
// features/login/ui/LoginForm.tsx
import { Button } from '@shared/ui/Button'; // OK: Feature uses Shared UI via alias
import { getUser } from '@entities/user'; // OK: Feature uses User entity via public API
`
- Allowed (Relative Import - Same Slice):
`javascript
// features/login/ui/LoginForm.tsx
import { validateInput } from '../lib/validation'; // OK: Relative import within the 'login' feature slice
`
- Disallowed (Relative Import - Cross Slice/Layer):
`javascript
// features/login/ui/LoginForm.tsx
import { config } from '../../../app/config'; // BAD: Relative path to different layer
import { User } from '../../entities/user/model/types'; // BAD: Relative path + Public API sidestep
`
- Disallowed (Public API Sidestep):
`javascript
// features/login/ui/LoginForm.tsx
import { userSlice } from '@entities/user/model/slice'; // BAD: Importing internal module directly
`
- Disallowed (Cross-Slice Dependency):
`javascript
// features/login/model/auth.ts
import { startRegistration } from '@features/registration'; // BAD: 'login' feature directly imports 'registration' feature
`

> 💡 Tip: Sticking to these import rules, especially using aliases and respecting public APIs, makes your codebase much easier to refactor and maintain.

---

🔍 Supported Rules

This plugin provides a set of ESLint rules that enforce Feature-Sliced Design (FSD) best practices.

Each rule helps maintain a clear module structure, enforce import constraints, and prevent architectural violations.

| Rule | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| fsd/forbidden-imports | Prevents imports from higher layers and cross-imports between slices. |
| fsd/no-relative-imports | Disallows relative imports across different slices or layers. Allows relative imports within the same slice. |
| fsd/no-public-api-sidestep | Prevents direct imports from internal modules, enforcing public API usage. |
| fsd/no-cross-slice-dependency | Disallows direct dependencies between slices in the same layer (applies to all layers, not just features). |
| fsd/no-ui-in-business-logic | Prevents UI imports inside business logic layers (e.g., entities). |
| fsd/no-global-store-imports | Forbids direct imports of global state (store). |
| fsd/ordered-imports | Enforces import grouping by layer. |

---

📌 Rule Details & Examples

$3

Prevents imports from higher layers and cross-imports between slices.

✅ Allowed: features can import from entities or shared

❌ Not Allowed: features importing directly from app


`js
// ❌ Incorrect (feature importing from app)
import { config } from '../../app/config';

// ✅ Correct (feature importing from entities/shared)
import { getUser } from '../../entities/user';
import { formatCurrency } from '../../shared/utils';
`

$3

Disallows relative imports across different slices or layers.

✅ Allowed: Using project-defined aliases or relative imports within same slice

❌ Not Allowed: Relative imports between different slices


`javascript
// ❌ Incorrect (relative import across different slices)
import { fetchUser } from '../another-slice/model/api';

// ✅ Correct (relative import within the same slice)
import { fetchData } from '../model/api';

// ✅ Correct (alias import across slices or layers)
import { Button } from '@shared/ui/Button';
// Also supports @/shared format
import { Button } from '@/shared/ui/Button';
`

#### Available options:

`javascript
// In your eslint.config.js:
'fsd/no-relative-imports': ['error', {
// Allow relative imports within the same slice (enabled by default)
allowSameSlice: true,

// Allow type-only imports to use relative paths (disabled by default)
allowTypeImports: false,

// Patterns for test files that can ignore this rule
testFilesPatterns: ['\\.test\\.', '\\.spec\\.'],

// Patterns for imports to ignore
ignoreImportPatterns: []
}]
`

$3

Prevents direct imports from internal modules of features, widgets, or entities.

✅ Allowed: Importing from index.ts (public API) or segment level

❌ Not Allowed: Importing internal files within segments


`javascript
// ✅ Correct (importing via public API)
import { authSlice } from '../../features/auth';
import { userModel } from '@entities/user/model'; // Segment level is allowed

// ❌ Incorrect (direct internal import)
import { authSlice } from '../../features/auth/slice.ts';
import { userSlice } from '@entities/user/model/slice'; // Internal file not allowed
`

Note: Any segment name is allowed (not limited to model/ui/api/lib). This provides flexibility for teams to define their own segment structure.

$3

Prevents direct dependencies between slices in the same layer (applies to all layers, not just features).

✅ Allowed: Communication via lower layers

❌ Not Allowed: Direct imports between different slices in the same layer


`javascript
// ❌ Incorrect (slice importing from another slice in the same layer)
import { processPayment } from '../../features/payment';

// ✅ Correct (using entities/shared as an intermediary)
import { PaymentEntity } from '../../entities/payment';

// ❌ Also incorrect (entities slice importing from another entities slice)
import { Product } from '../../entities/product';
// This rule now applies to all layers, not just features!
`

$3

Prevents UI imports inside business logic layers (e.g., entities).

✅ Allowed: UI should only be used inside widgets or pages

❌ Not Allowed: entities importing UI components


`javascript
// ❌ Incorrect (entity importing widget)
import { ProfileCard } from '../../widgets/ProfileCard';

// ✅ Correct (widget using entity data)
import { getUser } from '../../entities/user';
`

$3

Forbids direct imports of global state (store).

✅ Allowed: Using useStore or useSelector

❌ Not Allowed: Direct imports of the store


`javascript
// ❌ Incorrect (direct import of store)
import { store } from '../../app/store';

// ✅ Correct (using hooks)
import { useStore } from 'zustand';
import { useSelector } from 'react-redux';
`

$3

Enforces import grouping by layer.

✅ Allowed: Grouping imports by layer

❌ Not Allowed: Mixed import order


`javascript
// ❌ Incorrect (random import order)
import { processPayment } from '../features/payment';
import { getUser } from '../entities/user';
import { formatCurrency } from '../shared/utils';
import { loginUser } from '../features/auth';
import { Header } from '../widgets/Header';
import { useStore } from '../app/store';

// ✅ Correct (layered grouping)
import { useStore } from '../app/store'; // App

import { loginUser } from '../features/auth'; // Features
import { processPayment } from '../features/payment';

import { getUser } from '../entities/user'; // Entities

import { formatCurrency } from '../shared/utils'; // Shared

import { Header } from '../widgets/Header'; // Widgets
`

> 💡 Tip: Use npx eslint --fix to automatically reorder imports according to FSD layers.

---

🛠 Auto-fix Support

Certain rules in eslint-plugin-fsd-lint support automatic fixing using ESLint's --fix option.

This allows developers to quickly resolve violations without manual code adjustments.

$3

The following rules can be automatically fixed:

| Rule | Description |
| ----------------------- | ------------------------------------------------------------------------ |
| fsd/ordered-imports | Automatically sorts imports based on Feature-Sliced Design (FSD) layers. |

$3

To apply automatic fixes to your project, simply run:

`shell
npx eslint --fix your-file.js
`

Or, to fix all files in your project:

`shell
npx eslint --fix .
`

$3

❌ Before (fsd/ordered-imports violation)

`javascript
import { processPayment } from '../features/payment';
import { getUser } from '../entities/user';
import { formatCurrency } from '../shared/utils';
import { loginUser } from '../features/auth';
import { Header } from '../widgets/Header';
import { useStore } from '../app/store';
`

✅ After (npx eslint --fix applied)

`javascript
import { useStore } from '../app/store'; // App

import { loginUser } from '../features/auth'; // Features
import { processPayment } from '../features/payment';

import { getUser } from '../entities/user'; // Entities

import { formatCurrency } from '../shared/utils'; // Shared

import { Header } from '../widgets/Header'; // Widgets
`

> 💡 Tip: fsd/ordered-imports ensures a clean and structured import order based on FSD layers.

---

🆕 New Features

$3

The plugin now works seamlessly on both Windows and Unix-based systems by normalizing file paths internally.

$3

You can now use numbered prefixes or other naming conventions for your folders:

`js
// Configure folder pattern support
"fsd/forbidden-imports": ["error", {
folderPattern: {
enabled: true,
regex: "^(\\d+_)?(.*)",
extractionGroup: 2
}
}]
`

This allows using structures like:

`
src/
1_app/
2_pages/
3_widgets/
4_features/
5_entities/
6_shared/
`

$3

The plugin now supports both @shared and @/shared import styles:

`js
// Configure alias format
"fsd/forbidden-imports": ["error", {
alias: {
value: "@",
withSlash: false // Use true for @/shared format
}
}]
`

$3

The no-cross-slice-dependency rule now applies to all layers by default, not just features:

`js
// Restrict to features layer only (legacy behavior)
"fsd/no-cross-slice-dependency": ["error", {
featuresOnly: true
}]
`

$3

Multiple configuration presets are now available:

- recommended - Standard recommended settings
- strict - Maximum enforcement
- base - Less strict settings for easy adoption

$3

The plugin now includes extensive test cases for all rules, covering:

- Basic import scenarios
- Edge cases and complex patterns
- Path variations (Windows, Unix, mixed)
- Custom configurations
- Real-world usage examples

$3

The plugin now properly handles various path alias formats:

`javascript
// Both formats are supported
import { UserCard } from '@entities/user';
import { UserCard } from '@/entities/user';
`

$3

All rules now support dynamic imports:

`javascript
// Valid dynamic imports
const UserCard = await import('@entities/user');
const { UserCard } = await import('@entities/user');

// Invalid dynamic imports (will be caught by rules)
const UserCard = await import('@entities/user/ui');
`

$3

All rules are now thoroughly tested with:

- Basic import scenarios
- Edge cases and complex patterns
- Path variations (Windows, Unix, mixed)
- Custom configurations
- Real-world usage examples
- Path alias formats
- Dynamic import patterns

---

🤝 Contributing

We welcome contributions to improve eslint-plugin-fsd-lint`!

If you have an idea for a new rule or an improvement, feel free to submit a Pull Request.

Check out our contribution guide.

---

📝 License

This project is licensed under the MIT License.

See the LICENSE file for details.