Agent-Skills.md

Agent Skills: Architecture (Feature-Sliced Design)

Structure Next.js projects with Feature-Sliced Design layers, domain-grouped slices, and strict import hierarchy. Use when organizing features into FSD layers, enforcing slice boundaries, or keeping page.tsx thin. (triggers: src/features/**, src/entities/**, src/widgets/**, FSD, Feature Sliced Design, slices, segments)

UncategorizedID: hoangnguyen0403/agent-skills-standard/nextjs-architecture

Repository

hoangnguyen0403/agent-skills-standard
HoangNguyen0403License: Apache-2.0
362103

Install this agent skill to your local

pnpm dlx add-skill https://github.com/HoangNguyen0403/agent-skills-standard/tree/HEAD/skills/nextjs/nextjs-architecture

Skill Files

Browse the full folder contents for nextjs-architecture.

Download Skill

Loading file tree…

skills/nextjs/nextjs-architecture/SKILL.md

Skill Metadata

Name
nextjs-architecture
Description
"Structure Next.js projects with Feature-Sliced Design layers, domain-grouped slices, and strict import hierarchy. Use when organizing features into FSD layers, enforcing slice boundaries, or keeping page.tsx thin. (triggers: src/features/**, src/entities/**, src/widgets/**, FSD, Feature Sliced Design, slices, segments)"

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.

Workflow: Create a New Feature Slice

  1. Create feature folder — src/features/auth/login/ with ui/, model/, api/ segments.
  2. Add public API — Export via src/features/auth/login/index.ts.
  3. Wire into page — Import the feature widget in app/login/page.tsx (thin page).
  4. Verify imports — Ensure no upward or cross-slice imports violate the layer hierarchy.

Layer Hierarchy

App (app/) -> Widgets -> Features -> Entities -> Shared

See implementation examples for a thin page example.

Strategy

  1. RSC Boundaries: Enforce strict serialization rules for props passed from Server to Client. See RSC Boundaries & Serialization.
  2. App Layer is Thin: The app/ directory (App Router) is only for Routing.
    • Rule: page.tsx should only import Widgets/Features. No business logic (useEffect, fetch) directly in pages.
  3. 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.
  4. Layer Hierarchy: Code can only import from layers below it.
    • App -> Widgets -> Features -> Entities -> Shared.
  5. Avoid Excessive Entities: Do not preemptively create Entities.
    • Rule: Start logic in Features or Pages. Move to Entities only when data/logic is strictly reused across multiple differing features.
    • Rule: Simple CRUD belongs in shared/api, not entities.
  6. Standard Segments: Use standard segment names within slices.
    • ui (Components), model (State/actions), api (Data fetching), lib (Helpers), config (Constants).
    • Avoid: components, hooks, services as 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.tsx thin, containing only Widgets/Features and zero useEffect/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 in features/*/ui.

Anti-Patterns

  • No cross-slice imports: Slices in the same layer must not import from each other directly.
  • No business logic in page.tsx: Pages import Widgets/Features only; zero useEffect/fetch.
  • No file-type folders: Group by domain (features/auth/), not type (components/, hooks/).
  • No premature Entity creation: Start in Features; move to Entities only on strict reuse.