> nextjs-architecture
Scalable project structure using Feature-Sliced Design (FSD). Use when structuring a Next.js project with Feature-Sliced Design architecture. (triggers: src/features/**, src/entities/**, src/widgets/**, FSD, Feature Sliced Design, slices, segments)
curl "https://skillshub.wtf/HoangNguyen0403/agent-skills-standard/nextjs-architecture?format=md"Architecture (Feature-Sliced Design)
Priority: P2 (MEDIUM)
Adopt Feature-Sliced Design (FSD) for scalable applications. Warning: FSD introduces boilerplate. Use it only if the project is expected to grow significantly (e.g., 20+ features). For smaller projects, a simple module-based structure is preferred.
Strategy
- RSC Boundaries: Enforce strict serialization rules for props passed from Server to Client. See RSC Boundaries & Serialization.
- App Layer is Thin: The
app/directory (App Router) is only for Routing.- Rule:
page.tsxshould only import Widgets/Features. No business logic (useEffect,fetch) directly in pages.
- Rule:
- Slices over Types: Group code by Business Domain (User, Product, Cart), not by File Type (Components, Hooks, Utils).
- Bad:
src/components/LoginForm.tsx,src/hooks/useLogin.ts - Good:
src/features/auth/login/containing both.
- Bad:
- Layer Hierarchy: Code can only import from layers below it.
App->Widgets->Features->Entities->Shared.
- Avoid Excessive Entities: Do not preemptively create Entities.
- Rule: Start logic in
FeaturesorPages. Move toEntitiesonly when data/logic is strictly reused across multiple differing features. - Rule: Simple CRUD belongs in
shared/api, notentities.
- Rule: Start logic in
- Standard Segments: Use standard segment names within slices.
ui(Components),model(State/actions),api(Data fetching),lib(Helpers),config(Constants).- Avoid:
components,hooks,servicesas segment names.
Structure Reference
For the specific directory layout and layer definitions, see the reference documentation.
Architecture Checklist (Mandatory)
-
Layer Imports: Does any layer import from a layer ABOVE it? (App > Widgets > Features > Entities > Shared)
-
Page Logic: Is
page.tsxthin, containing only Widgets/Features and zerouseEffect/fetch? -
RSC Boundaries: Are Server Components isolated from Client Components with proper 'use client' boundaries?
-
Public API: Is all access to a slice performed via the top-level
index.ts(public API)? -
Cross-Slice: Do slices within the same layer (e.g., two features) import from each other directly? (Prohibited)
-
Server Actions: Place them in the
model/folder of a Feature (e.g.,features/auth/model/actions.ts). -
Data Access (DAL): Place logic in the
model/folder of an Entity (e.g.,entities/user/model/dal.ts). -
UI Components: Base UI (shadcn) belongs in
shared/ui. Feature-specific UI belongs infeatures/*/ui.
🚫 Anti-Patterns
- Do NOT use standard patterns if specific project rules exist.
- Do NOT ignore error handling or edge cases.
> related_skills --same-repo
> typescript-tooling
Development tools, linting, and build config for TypeScript. Use when configuring ESLint, Prettier, Jest, Vitest, tsconfig, or any TS build tooling. (triggers: tsconfig.json, .eslintrc.*, jest.config.*, package.json, eslint, prettier, jest, vitest, build, compile, lint)
> typescript-security
Secure coding practices for TypeScript. Use when validating input, handling auth tokens, sanitizing data, or managing secrets and sensitive configuration. (triggers: **/*.ts, **/*.tsx, validate, sanitize, xss, injection, auth, password, secret, token)
> typescript-language
Modern TypeScript standards for type safety and maintainability. Use when working with types, interfaces, generics, enums, unions, or tsconfig settings. (triggers: **/*.ts, **/*.tsx, tsconfig.json, type, interface, generic, enum, union, intersection, readonly, const, namespace)
> typescript-best-practices
Idiomatic TypeScript patterns for clean, maintainable code. Use when writing or refactoring TypeScript classes, functions, modules, or async logic. (triggers: **/*.ts, **/*.tsx, class, function, module, import, export, async, promise)