Clarify the Entities vs Features boundary as Read vs Write and add Server‑first guidance (with decision tree, cheat‑sheet, and pitfalls)

[boaz-hwang]

Summary

This PR proposes a focused clarification to Feature‑Sliced Design (FSD):

• Define Entities as read‑only, pure UI/data views (same input → same output).
• Define Features as all forms of write/interaction (domain writes, URL writes, client‑state writes, and side‑effects).
• Add a field‑tested decision tree, rules of thumb, classification tables, and common pitfalls to help teams keep boundaries intact.
• Provide an optional, stack‑agnostic Server‑first appendix (with Next.js/RSC as one concrete mapping).

The proposal does not change the layer model, slice/segment rules, or public API rules. It tightens semantics that already exist in FSD and offers pragmatic guardrails that reflect real‑world usage. See FSD layer and slice/segment references for context. ([feature-sliced.design]1)

---

Motivation

Teams frequently blur boundaries by:

• Adding onClick or router hooks to Entities.
• Computing URLs inside lower layers.
• Mixing display and interaction, which harms caching, bundle size, and testability.

While FSD defines layers (app → … → entities → shared) and segments (ui, api, model, etc.), the docs stop short of a crisp, testable boundary heuristic for Entities vs Features. This PR supplies that heuristic and maps it to modern Server‑first rendering where appropriate. ([feature-sliced.design]1)

Additionally, the current “Routing” issue page (WIP) warns about URL logic leaking into lower layers; this PR contributes concrete guidance and examples to operationalize that page. ([feature-sliced.design]2)

---

Scope of change (documentation only)

• New guide: “Read vs Write boundary: Entities (Read) and Features (Write)”

• New appendix: “Server‑first mapping (Next.js RSC example)”

• Updates to:

  • Entities reference — clarify purity & allowed links.
  • Features reference — explicitly enumerate “write” categories and ownership.
  • Code smells/Issues → Routing — add prescriptive rules for href ownership and URL builders.
  • Testing guidance (brief) — where snapshot/a11y vs E2E/interaction tests belong.

No normative changes to import rules, slices/segments, or public API. Cross‑imports and @x remain as documented. ([feature-sliced.design]3)

---

Proposed content (draft)

1) Definitions

Entities (Read)

• Purpose: Pure, reusable rendering of business concepts.
• Behavior: Given the same input, returns the same markup (pure view).
• No local interaction handlers, router mutations, side‑effects, timers, or implicit state.
• May render links given via props (href computed elsewhere).
• Typical segments: ui for view, model for view types/schemas, api for read/SELECT helpers if needed. ([feature-sliced.design]1)

Features (Write)

• Purpose: All user interactions and writes.

• Categories:

  1. Domain write (server/data): create/update/delete (e.g., “Quiz”, “User”).
  2. State write (client/URL): infinite scroll, filter, sort, search, pagination, selection, clipboard, downloads, prefetch, sockets, etc.

• Owns handlers (on*), URL/query changes, side‑effects, optimistic UX, permissions for actions, and testing of interactions.

• Typical segments: ui (forms/buttons/observers), model (local state/validators), api (mutations). ([feature-sliced.design]1)

Mapping note (unchanged FSD semantics): Features = “main interactions users care about”, Entities = “business concepts.” This PR sharpens that distinction using Read vs Write as a practical boundary that teams can test/enforce. ([feature-sliced.design]1)

---

2) Rules of thumb (operational)

1. If you see an on* handler, it belongs in Features.
2. If you touch the router/URL, it’s Features (URL is state; changing it is a write).
3. Links are allowed in Entities only if the href is provided by upper layers (Pages/Features) and does not compute or mutate view conditions.
4. When unsure, decide by “Who owns the action?” and “Same input → same output?” If it writes (domain/URL/client‑state/side‑effects) → Features.

Routing addendum: avoid hard‑coding URLs in lower layers; pass them down from Pages/Features via props/builders. ([feature-sliced.design]2)

---

3) Decision tree

1. Does this component trigger any write?
   (DB, URL, client state, side‑effects like clipboard, prefetch, socket)
   → Yes: Features. → No: go to 2.

2. Is it pure? (Same input ⇒ same markup.)
   → Yes: Entities. → No: likely Features decides conditions and injects props to an Entity view.

3. Is it a link?

   • Resource navigation (no condition write): Entities can render the link given an href prop.
   • View/condition change (filters, panel/modals via query): Features builds and owns the href.

---

4) Server‑first appendix (optional, stack‑agnostic; Next.js as example)

• Intent: show one concrete mapping; FSD remains stack‑agnostic.

• Mapping (Next.js App Router):

  • Entities → Server Components by default (fetch + render on server; cache/stream as appropriate).
  • Features → Client Components (handlers, URL writes) + Server Actions for domain writes.
  • Benefits: smaller bundles, predictable caching, clearer tests. ([Next.js]4)

Minimal folder sketch (fits existing FSD layers/segments):

src/
├─ pages|app/ …                          # routing/composition
├─ entities/
│  └─ <domain>/<read-view>/
│     ├─ ui/*.tsx                        # pure views (server-first)
│     └─ action/get*.ts                  # SELECT-only helpers (optional)
├─ features/
│  └─ <feature>/<intent>/
│     ├─ ui.tsx                          # client component (handlers)
│     ├─ model/state.ts                  # client state (optional)
│     └─ action/*.ts                     # server actions (POST/PUT/DELETE)
├─ widgets/
├─ shared/ (ui|lib|api|config|routes|i18n)

(Still honors layers, segments, public API, and import rules.) ([feature-sliced.design]1)

---

5) Classification cheat‑sheet (abridged)

• Entities: resource details/card/table/chart display, static breadcrumbs/nav, static SEO/OG output, audit log view, loading skeletons/empty states (pure), resource links (href passed in).
• Features: filter/sort/search/pagination/infinite scroll, create/update/delete, optimistic updates, drafts/autosave, file upload/download (generated), selection/bulk actions, tooltips with state, sockets/SSE/presence, prefetch on hover/in‑view, route guards/redirects, A/B switches & analytics, geolocation & permissions, PWA prompts, query‑based modals/panels, payment/queues, toasts & retry, error boundaries with recovery.

---

6) Testing guidance (brief)

• Entities → snapshot + a11y; contract tests for props.
• Features → interaction/E2E (happy path, rollback, routing, side‑effects).

---

7) Common pitfalls (and fixes)

• Router/URL in Entities (useSearchParams, router.*) → move to Features, pass props/href down.
• “Just one onClick” in Entity → becomes a write; move to Feature.
• Hardcoded URLs in lower layers → push up to Pages/Features; supply href via props/builders. ([feature-sliced.design]2)
• Wildcard public APIs or cross‑imports without @x → follow Public API rules and @x notation. Consider Steiger for enforcement. ([feature-sliced.design]3)

---

Backward compatibility

• No breaking changes.
• Purely documentary; aligns with existing layers, slices/segments, public API, and routing guidance. ([feature-sliced.design]1)

---

Alternatives considered

• Keep Entities/Features definitions as‑is and rely on team conventions.

  • Rejected: leaves teams without a crisp, testable boundary; recurring confusion around links, URL writes, and handlers.

---

Open questions for maintainers

1. Where should the URL‑write rule live long‑term — in Routing (Guides/Issues) or Entities/Features references (cross‑linked)? ([feature-sliced.design]2)
2. Should we include a short linters/tooling sidebar (e.g., Steiger rule examples) in Public API/import rules? ([feature-sliced.design]3)
3. Would you accept a framework‑appendix pattern (Next.js first, then Vue/Nuxt, SvelteKit, Angular) to keep the core spec stack‑agnostic?

---

Checklist

• Adds a new guide with decision tree, rules of thumb, and cheat‑sheet.
• Updates Entities/Features references with explicit Read vs Write semantics. ([feature-sliced.design]1)
• Strengthens Routing guidance with href ownership and examples. ([feature-sliced.design]2)
• Adds a Server‑first appendix referencing RSC/Next.js docs as one mapping example (optional). ([Next.js]4)
• No code changes; docs only.

---

Appendix: References (for reviewers)

• Layers and meanings; import rule; Entities/Features definitions. ([feature-sliced.design]1)
• Slices & Segments (ui, api, model, lib, config). ([feature-sliced.design]5)
• Public API (including @x for cross‑imports). ([feature-sliced.design]3)
• Routing (WIP) — avoid URL logic in lower layers; centralize at Pages and pass down. ([feature-sliced.design]2)
• Next.js RSC — server/client components and rendering strategies (example mapping only). ([Next.js]4)

---

If maintainers agree with the direction, I can follow up by splitting this into:

1. a new guide page (Read vs Write boundary),
2. a short Entities/Features reference edit, and
3. a Routing page PR with examples.

[illright]

I'm sorry, but this text looks AI-generated to me. If I'm wrong about my assumption, could you please edit the message to explain your thought more briefly?