FSD in Next.js zonder cyclische import: lagen, publieke API en automatische verificatie
Waar komen cycli vandaan?
De agent voegt de functie “toevoegen aan favorieten” toe. Het heeft het type Product nodig, het importeert het van entities/product. Vervolgens moet u een favorietenknop in de productkaart insluiten, en de agent importeert features/favorites rechtstreeks in entities/product/ui/ProductCard.tsx. Het resultaat is een cyclus: de essentie hangt af van het kenmerk, het kenmerk van de essentie. In runtime manifesteert dit zich als undefined voor de geïmporteerde waarde tijdens module-initialisatie, en in assemblage als een onvoorspelbare volgorde van chunks.
FSD lost dit op met één regel: een module kan alleen importeren uit lagen die strikt onder zichzelf liggen, en segmenten van dezelfde laag weten niets van elkaar.
Lagen en richting van afhankelijkheden
app → инициализация, провайдеры, глобальные стили pages → композиция страниц widgets → крупные самостоятельные блоки (шапка, лента, карточка с действиями) features → пользовательские действия (добавить в избранное, авторизоваться) entities → бизнес-сущности (product, user, order) shared → UI-кит, утилиты, api-клиент, конфиг; без бизнес-логики
Importeren is alleen toegestaan van boven naar beneden: widgets kan features, entities, shared gebruiken; Alleen entities - shared. shared importeert niets uit de bovenstaande lagen.
Het favorietenvoorbeeld wordt opgelost door compositie op een hoger niveau: ProductCard van entities neemt het actions slot, en widgets/product-list geeft daar een knop door van 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} />} />);
}API voor openbare segmenten
Elk segment exporteert alleen wat is gedeclareerd in zijn index.ts:
// entities/product/index.ts
export { ProductCard } from "./ui/ProductCard";
export type { Product } from "./model/types";
export { getProduct } from "./api/getProduct";Het importeren van @/entities/product/ui/ProductCard en het omzeilen van index.ts is verboden. Hierdoor kunt u de interne structuur van het segment wijzigen zonder dat dit gevolgen heeft voor de consument.
Wanneer entiteiten van elkaar moeten weten
Order bevat Product en het besteltype verwijst naar het producttype. Voor dergelijke gevallen heeft FSD de notatie @x - een afzonderlijke openbare API voor een specifieke buur:
// 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 }[] };Deze relatie is zichtbaar en beperkt tot typen. Als de logica door @x begint te stromen, is dit een signaal dat de entiteiten moeten worden gecombineerd of gemeenschappelijk in shared moeten worden geplaatst.
Next.js App-router en FSD
De mappen app en pages in FSD hebben dezelfde naam als de Next.js-routering. Aanbevolen optie: Next.js-routering blijft in de root app/, FSD-lagen leven in src/ en routebestanden exporteren alleen pagina's opnieuw:
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 RouterAutomatische controle
De agent overtreedt de regels zonder bij de eerste gelegenheid te controleren. De drie instrumenten vullen elkaar aan.
Steiger - officiële FSD-linter, controleert de structuur, openbare API en richting van import:
npx steiger ./src
ESLint met import/no-restricted-paths verhindert het rechtstreeks importeren van lagen in de editor:
// 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"] },
],
}],
},
},
];Verbod op cross-import binnen één laag (features/a → features/b) wordt gecontroleerd door Steiger; ESLint-zones drukken dit niet uit zonder elk segment te vermelden.
madge vindt reeds bestaande lussen in het project:
npx madge --circular --extensions ts,tsx --ts-config tsconfig.json src
import/no-cycle bij een groot project vertraagt de pluisvorming aanzienlijk; het kan alleen in CI worden uitgevoerd, waarbij zones in de editor achterblijven.
Agentregel
- Слои: app > pages > widgets > features > entities > shared. Импорт только вниз. - Слайсы одного слоя не импортируют друг друга. Связь — через композицию на слое выше. - Импорт из слайса только через его index.ts. - Типы соседней сущности — только через entities/<name>/@x/<consumer>.ts. - После изменений запусти npx steiger ./src и исправь все ошибки.
Wanneer FSD niet nodig is
Voor een landingspagina, beheerderspaneel voor een tiental schermen of een prototype voegt FSD meer mappen toe dan nuttig is. Het is voldoende om components, lib en app te scheiden en import/no-cycle op te nemen. De methodologie loont wanneer meerdere mensen of agenten tegelijkertijd aan de code werken en er meer dan twintig functies zijn.