🚀 eslint-plugin-fsd-lint

ESLint 9+ plugin for enforcing Feature-Sliced Design rules with Flat Config support.

Overview

eslint-plugin-fsd-lint helps you keep a Feature-Sliced Design codebase predictable as it grows. It focuses on the rules that usually start drifting first:

layer boundaries
public API discipline
same-layer slice isolation
relative import hygiene
UI/business-logic separation
stable import ordering

It is built for modern ESLint setups and works with:

ESLint 9+
Flat Config
JavaScript and TypeScript projects
Windows and Unix-style paths
both @shared/... and @/shared/... aliases
custom folder naming like 1_app, 2_pages, 5_features
custom source roots through rootPath

Installation

Install the plugin and make sure ESLint 9+ is available in your project.

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

Or with pnpm:

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

Quick Start

Recommended Preset

Use the built-in preset if you want sensible defaults with minimal setup.

import fsdPlugin from "eslint-plugin-fsd-lint";

export default [fsdPlugin.configs.recommended];

Strict Preset

Use strict when you want all architectural checks to fail the build. This preset also requires slice-level public API imports and applies public API enforcement to shared.

import fsdPlugin from "eslint-plugin-fsd-lint";

export default [fsdPlugin.configs.strict];

Base Preset

Use base if you are gradually adopting FSD rules in an existing codebase.

import fsdPlugin from "eslint-plugin-fsd-lint";

export default [fsdPlugin.configs.base];

Recommended preset configuration

{
  plugins: {
    fsd: fsdPlugin,
  },
  rules: {
    "fsd/forbidden-imports": "error",
    "fsd/no-cross-slice-dependency": "error",
    "fsd/no-global-store-imports": "error",
    "fsd/no-public-api-sidestep": "error",
    "fsd/no-relative-imports": "error",
    "fsd/no-ui-in-business-logic": "error",
    "fsd/ordered-imports": "warn",
  },
}

Strict preset configuration

{
  plugins: {
    fsd: fsdPlugin,
  },
  rules: {
    "fsd/forbidden-imports": "error",
    "fsd/no-cross-slice-dependency": "error",
    "fsd/no-global-store-imports": "error",
    "fsd/no-public-api-sidestep": [
      "error",
      {
        publicApi: {
          allowSegmentImports: false,
          enforceShared: true,
        },
      },
    ],
    "fsd/no-relative-imports": "error",
    "fsd/no-ui-in-business-logic": "error",
    "fsd/ordered-imports": "error",
  },
}

Base preset configuration

{
  plugins: {
    fsd: fsdPlugin,
  },
  rules: {
    "fsd/forbidden-imports": "warn",
    "fsd/no-cross-slice-dependency": "warn",
    "fsd/no-global-store-imports": "error",
    "fsd/no-public-api-sidestep": "warn",
    "fsd/no-relative-imports": "off",
    "fsd/no-ui-in-business-logic": "error",
    "fsd/ordered-imports": "warn",
  },
}

Manual Configuration

Use manual configuration when you want fine-grained control over each rule.

import fsdPlugin from "eslint-plugin-fsd-lint";

export default [
  {
    plugins: {
      fsd: fsdPlugin,
    },
    rules: {
      "fsd/forbidden-imports": "error",
      "fsd/no-relative-imports": "error",
      "fsd/no-public-api-sidestep": "error",
      "fsd/no-cross-slice-dependency": "error",
      "fsd/no-ui-in-business-logic": "error",
      "fsd/no-global-store-imports": "error",
      "fsd/ordered-imports": "warn",
    },
  },
];

What The Rules Enforce

Layer direction: higher layers cannot import from lower-priority layers they should not know about.
Slice isolation: one slice cannot reach directly into another slice in the same layer.
Public APIs: other slices should import through index.ts, index.js, or allowed segment-level public entry points.
Stable imports: cross-slice and cross-layer imports should use aliases instead of brittle relative paths.
Business logic purity: model/api/lib code should not pull UI code into places where it does not belong.
Readable import blocks: FSD imports are grouped in a predictable order.

Common Configuration Options

Several rules support the same core options.

Option	Purpose	Example
`alias`	Defines the import alias format for your project.	`{ value: '@', withSlash: false }`
`rootPath`	Tells the plugin where the FSD tree starts in the absolute file path. Useful for monorepos or nested apps.	`'/apps/web/src/'`
`folderPattern`	Supports numbered or customized layer directory names.	`{ enabled: true, regex: '^(\\d+_)?(.*)', extractionGroup: 2 }`
`testFilesPatterns`	Allows test files to bypass specific architectural rules.	`['*/.test.', '/.spec.*']`
`ignoreImportPatterns`	Skips selected import paths for a rule.	`['/types$', '^virtual:']`

`rootPath` Example

If your project does not start directly at /src/, set rootPath so file-path based rules can still resolve the current layer and slice correctly.

import fsdPlugin from "eslint-plugin-fsd-lint";

export default [
  {
    plugins: {
      fsd: fsdPlugin,
    },
    rules: {
      "fsd/forbidden-imports": ["error", { rootPath: "/apps/storefront/src/" }],
      "fsd/no-cross-slice-dependency": [
        "error",
        { rootPath: "/apps/storefront/src/" },
      ],
      "fsd/no-ui-in-business-logic": [
        "error",
        { rootPath: "/apps/storefront/src/" },
      ],
    },
  },
];

Typical rootPath values:

'/src/'
'/apps/web/src/'
'/packages/admin/src/'
'/src/root/'

The value should match a stable segment inside the absolute path ESLint sees for your files.

Next.js App Router and Custom Layer Folder Names

Next.js App Router projects can keep Next's route files in src/app and use FSD layers for the rest of the application.

The recommended setup is to keep the standard FSD layer folder names (app, pages, widgets, features, entities, shared). Without a layers override, the plugin uses its built-in FSD folder names (app, processes, pages, widgets, features, entities, shared) by default, so existing projects that still use processes remain supported. Custom layer folder names are supported for existing projects, migrations, or framework constraints, but they are not recommended as a default choice because they make FSD conventions less recognizable.

If your project uses screens instead of the FSD pages folder name, map the pages layer to the screens folder with layers.pages.pattern in eslint.config.js. The same pattern works for other layer folder names as well. Keep the canonical FSD layer keys in the config and set each layer's pattern to the folder name used by your project.

import fsdPlugin from "eslint-plugin-fsd-lint";

const fsdOptions = {
  rootPath: "/src/",
  alias: {
    value: "@",
    withSlash: true,
  },
  layers: {
    app: {
      pattern: "app",
    },
    pages: {
      pattern: "screens",
    },
    widgets: {
      pattern: "blocks",
    },
    features: {
      pattern: "actions",
    },
    entities: {
      pattern: "domain",
    },
    shared: {
      pattern: "common",
    },
  },
  ignoreImportPatterns: ["\\.css$"],
};

export default [
  {
    files: ["src/**/*.{js,jsx,ts,tsx}"],
    plugins: {
      fsd: fsdPlugin,
    },
    rules: {
      "fsd/forbidden-imports": ["error", fsdOptions],
      "fsd/no-cross-slice-dependency": ["error", fsdOptions],
      "fsd/no-public-api-sidestep": ["error", fsdOptions],
      "fsd/no-relative-imports": [
        "error",
        {
          ...fsdOptions,
          allowSameSlice: true,
        },
      ],
      "fsd/no-global-store-imports": "error",
      "fsd/ordered-imports": ["warn", fsdOptions],
    },
  },
];

src/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   └── api/health/route.ts
├── screens/
│   └── dashboard/
├── blocks/
├── actions/
├── domain/
└── common/

Options such as allowedToImport, excludeLayers, publicApi.enforceForLayers, and ordered-imports.customOrder still use the canonical layer keys (app, pages, widgets, features, entities, shared). The pattern value is the folder/import segment used on disk. For new projects, prefer the standard layer folder names unless there is a clear reason to do otherwise.

Advanced Configuration

import fsdPlugin from "eslint-plugin-fsd-lint";

export default [
  {
    plugins: {
      fsd: fsdPlugin,
    },
    rules: {
      "fsd/forbidden-imports": [
        "error",
        {
          rootPath: "/apps/web/src/",
          alias: {
            value: "@",
            withSlash: false,
          },
          folderPattern: {
            enabled: true,
            regex: "^(\\d+_)?(.*)",
            extractionGroup: 2,
          },
        },
      ],
      "fsd/no-cross-slice-dependency": [
        "error",
        {
          rootPath: "/apps/web/src/",
          featuresOnly: false,
          allowTypeImports: true,
        },
      ],
      "fsd/no-ui-in-business-logic": [
        "error",
        {
          rootPath: "/apps/web/src/",
          businessLogicLayers: ["model", "api", "lib"],
          uiLayers: ["ui", "widgets", "features"],
        },
      ],
      "fsd/no-relative-imports": [
        "error",
        {
          allowSameSlice: true,
          allowTypeImports: false,
        },
      ],
    },
  },
];

Example Project Structure

src/
├── app/
│   ├── providers/
│   ├── store/
│   └── index.ts
├── processes/
├── pages/
│   └── login/
│       ├── ui/
│       └── index.ts
├── widgets/
│   └── header/
│       ├── ui/
│       └── index.ts
├── features/
│   └── auth/
│       ├── api/
│       ├── lib/
│       ├── model/
│       ├── ui/
│       └── index.ts
├── entities/
│   └── user/
│       ├── model/
│       ├── ui/
│       └── index.ts
└── shared/
    ├── api/
    ├── config/
    ├── lib/
    └── ui/

Numbered folders also work when folderPattern is enabled:

src/
├── 1_app/
├── 2_pages/
├── 3_widgets/
├── 4_features/
├── 5_entities/
└── 6_shared/

Rules

Rule	What it protects	Key options
`fsd/forbidden-imports`	Layer direction and invalid layer-to-layer imports	`alias`, `rootPath`, `folderPattern`, `ignoreImportPatterns`
`fsd/no-relative-imports`	Relative imports across slices or layers	`allowSameSlice`, `allowTypeImports`, `ignoreImportPatterns`
`fsd/no-public-api-sidestep`	Direct access to internal modules	`publicApi`, `ignoreImportPatterns`
`fsd/no-cross-slice-dependency`	Direct dependencies between slices in the same layer	`rootPath`, `featuresOnly`, `allowTypeImports`, `excludeLayers`
`fsd/no-ui-in-business-logic`	UI imports inside model/api/lib code	`rootPath`, `uiLayers`, `businessLogicLayers`, `allowTypeImports`
`fsd/no-global-store-imports`	Direct store imports	`ignoreImportPatterns`
`fsd/ordered-imports`	Stable FSD import ordering	no options

Rule Examples

`fsd/forbidden-imports`

// features/auth/model/service.ts

// ✅ allowed
import { getUser } from "@entities/user";
import { Button } from "@shared/ui/Button";

// ❌ forbidden
import { LoginPage } from "@pages/login";

`fsd/no-relative-imports`

// features/auth/ui/LoginForm.tsx

// ✅ same-slice relative import
import { validateCredentials } from "../lib/validation";

// ❌ cross-layer relative import
import { store } from "../../../app/store";

// ✅ cross-layer alias import
import { store } from "@app/store";

`fsd/no-public-api-sidestep`

// ✅ public API import
import { authModel } from "@features/auth";

// ✅ segment-level public import
import { userModel } from "@entities/user/model";

// ❌ deep internal file import
import { authSlice } from "@features/auth/model/slice";

For stricter projects, segment-level public API imports can be disabled and the shared layer can be included in public API enforcement:

export default [
  {
    rules: {
      "fsd/no-public-api-sidestep": [
        "error",
        {
          publicApi: {
            allowSegmentImports: false,
            enforceShared: true,
          },
        },
      ],
    },
  },
];

`fsd/no-cross-slice-dependency`

// features/auth/model/service.ts

// ❌ direct dependency on another feature slice
import { profileService } from "@features/profile/model/service";

// ✅ dependency through lower layer
import { getProfile } from "@entities/profile";

`fsd/no-ui-in-business-logic`

// entities/user/model/user.ts

// ❌ business logic importing UI
import { Header } from "@widgets/header";

// ✅ business logic importing data or helpers
import { formatDate } from "@shared/lib/date";

`fsd/no-global-store-imports`

// ❌ direct store import
import { store } from "@app/store";

// ✅ use app wiring, hooks, or selectors instead
import { useSelector } from "react-redux";

`fsd/ordered-imports`

// Before
import { processPayment } from "@features/payment";
import { getUser } from "@entities/user";
import { formatCurrency } from "@shared/lib/currency";
import { useStore } from "@app/store";

// After --fix
import { useStore } from "@app/store";

import { processPayment } from "@features/payment";

import { getUser } from "@entities/user";

import { formatCurrency } from "@shared/lib/currency";

Auto-fix Support

fsd/ordered-imports supports ESLint auto-fix.

npx eslint --fix .

Troubleshooting

My app lives inside a monorepo package

Use rootPath on rules that rely on the current file path:

'fsd/forbidden-imports': ['error', { rootPath: '/packages/web/src/' }],
'fsd/no-cross-slice-dependency': ['error', { rootPath: '/packages/web/src/' }],
'fsd/no-ui-in-business-logic': ['error', { rootPath: '/packages/web/src/' }],

I use `@/shared/...` instead of `@shared/...`

'fsd/forbidden-imports': ['error', {
  alias: {
    value: '@',
    withSlash: true,
  },
}]

I use numbered layer directories

'fsd/forbidden-imports': ['error', {
  folderPattern: {
    enabled: true,
    regex: '^(\\d+_)?(.*)',
    extractionGroup: 2,
  },
}]

Development

npm run lint
npm test

Contributing

Issues and pull requests are welcome. Please include tests and documentation updates for any new rule or behavior change.

Name		Name	Last commit message	Last commit date
Latest commit History 104 Commits
.github		.github
src		src
test-project-next		test-project-next
test-project		test-project
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.ko.md		README.ko.md
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
vitest.config.js		vitest.config.js

Folders and files

Latest commit

History

Repository files navigation

🚀 eslint-plugin-fsd-lint

Overview

Installation

Quick Start

Recommended Preset

Strict Preset

Base Preset

Manual Configuration

What The Rules Enforce

Common Configuration Options

rootPath Example

Next.js App Router and Custom Layer Folder Names

Advanced Configuration

Example Project Structure

Rules

Rule Examples

fsd/forbidden-imports

fsd/no-relative-imports

fsd/no-public-api-sidestep

fsd/no-cross-slice-dependency

fsd/no-ui-in-business-logic

fsd/no-global-store-imports

fsd/ordered-imports

Auto-fix Support

Troubleshooting

My app lives inside a monorepo package

I use @/shared/... instead of @shared/...

I use numbered layer directories

Development

Contributing

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 13

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`rootPath` Example

`fsd/forbidden-imports`

`fsd/no-relative-imports`

`fsd/no-public-api-sidestep`

`fsd/no-cross-slice-dependency`

`fsd/no-ui-in-business-logic`

`fsd/no-global-store-imports`

`fsd/ordered-imports`

I use `@/shared/...` instead of `@shared/...`

Packages