循環インポートを使用しない Next.js の FSD: レイヤー、パブリック API、自動検証
Откуда берутся циклы
Агент добавляет фичу «добавить в избранное». Ему нужен тип Product, он импортирует его из entities/product. Затем в карточку товара нужно встроить кнопку избранного, и агент импортирует features/favorites прямо в entities/product/ui/ProductCard.tsx. Получился цикл: сущность зависит от фичи, фича от сущности. В рантайме это проявляется как undefined у импортированного значения при инициализации модуля, а в сборке — как непредсказуемый порядок чанков.
FSD решает это одним правилом: модуль может импортировать только из слоёв строго ниже себя, и слайсы одного слоя не знают друг о друге.
Слои и направление зависимостей
app → инициализация, провайдеры, глобальные стили pages → композиция страниц widgets → крупные самостоятельные блоки (шапка, лента, карточка с действиями) features → пользовательские действия (добавить в избранное, авторизоваться) entities → бизнес-сущности (product, user, order) shared → UI-кит, утилиты, api-клиент, конфиг; без бизнес-логики
Импорт разрешён только сверху вниз: widgets может использовать features, entities, shared; entities — только shared. shared не импортирует ничего из слоёв выше.
Пример с избранным решается композицией на уровне выше: ProductCard из entities принимает слот actions, а widgets/product-list передаёт туда кнопку из features/favorites.
// entities/product/ui/ProductCard.tsx
export function ProductCard({ product, actions }: { product: Product; actions?: React.ReactNode }) {
return (
<div>
<h3>{product.title}</h3>
<span>{product.price}</span>
{actions}
</div>
);
}
// widgets/product-list/ui/ProductList.tsx
import { ProductCard } from "@/entities/product";
import { ToggleFavorite } from "@/features/favorites";
export function ProductList({ items }: { items: Product[] }) {
return items.map(p => <ProductCard key={p.id} product={p} actions={<ToggleFavorite productId={p.id} />} />);
}Public API слайса
Каждый слайс экспортирует наружу только то, что объявлено в его index.ts:
// entities/product/index.ts
export { ProductCard } from "./ui/ProductCard";
export type { Product } from "./model/types";
export { getProduct } from "./api/getProduct";Импорт @/entities/product/ui/ProductCard в обход index.ts запрещён. Это позволяет менять внутреннюю структуру слайса, не трогая потребителей.
Когда сущностям нужно знать друг о друге
Order содержит Product, и тип заказа ссылается на тип товара. Для таких случаев в FSD есть нотация @x — отдельный public API для конкретного соседа:
// entities/product/@x/order.ts
export type { Product } from "../model/types";
// entities/order/model/types.ts
import type { Product } from "@/entities/product/@x/order";
export type Order = { id: string; items: { product: Product; qty: number }[] };Такая связь видна явно и ограничена типами. Если через @x начинает ходить логика, это сигнал, что сущности стоит объединить или вынести общее в shared.
Next.js App Router и FSD
Папки app и pages в FSD совпадают по имени с роутингом Next.js. Рекомендованный вариант: роутинг Next.js остаётся в корневой app/, слои FSD живут в src/, а файлы маршрутов только реэкспортируют страницы:
app/
products/[id]/page.tsx → export { ProductPage as default } from "@/pages/product";
src/
app/ # провайдеры, стили
pages/
widgets/
features/
entities/
shared/
pages/README.md # пустая корневая папка, чтобы Next.js не принял src/pages за Pages RouterАвтоматическая проверка
Правила без проверки агент нарушит при первом удобном случае. Три инструмента дополняют друг друга.
Steiger — официальный линтер FSD, проверяет структуру, public API и направление импортов:
npx steiger ./src
ESLint с import/no-restricted-paths запрещает импорт вверх по слоям прямо в редакторе:
// eslint.config.mjs (фрагмент)
import importPlugin from "eslint-plugin-import";
export default [
{
plugins: { import: importPlugin },
rules: {
"import/no-cycle": ["error", { maxDepth: 10 }],
"import/no-restricted-paths": ["error", {
zones: [
{ target: "./src/shared", from: ["./src/entities", "./src/features", "./src/widgets", "./src/pages", "./src/app"] },
{ target: "./src/entities", from: ["./src/features", "./src/widgets", "./src/pages", "./src/app"] },
{ target: "./src/features", from: ["./src/widgets", "./src/pages", "./src/app"] },
{ target: "./src/widgets", from: ["./src/pages", "./src/app"] },
],
}],
},
},
];Запрет кросс-импортов внутри одного слоя (features/a → features/b) проверяет Steiger; ESLint-зоны этого не выражают без перечисления каждого слайса.
madge находит уже существующие циклы в проекте:
npx madge --circular --extensions ts,tsx --ts-config tsconfig.json src
import/no-cycle на большом проекте заметно замедляет линтинг; его можно запускать только в CI, а в редакторе оставить зоны.
Правило для агента
- Слои: app > pages > widgets > features > entities > shared. Импорт только вниз. - Слайсы одного слоя не импортируют друг друга. Связь — через композицию на слое выше. - Импорт из слайса только через его index.ts. - Типы соседней сущности — только через entities/<name>/@x/<consumer>.ts. - После изменений запусти npx steiger ./src и исправь все ошибки.
Когда FSD — лишнее
Для лендинга, админки на десяток экранов или прототипа FSD добавляет больше папок, чем пользы. Достаточно разделить components, lib и app и включить import/no-cycle. Методология окупается, когда над кодом одновременно работают несколько людей или агентов и фич становится больше двух десятков.