);
}
```
### Feature (User Action)
```tsx
// features/ai-translate/ui/ai-translate-button.tsx
'use client';
import { Button } from '@/shared/ui/button';
import { useAITranslate } from '../model/use-ai-translate';
export function AITranslateButton({ keyId, targetLanguages }: Props) {
const { translate, isPending } = useAITranslate();
return (
);
}
```
### Entity (Business Object)
```tsx
// entities/project/ui/project-card.tsx
import Link from 'next/link';
import type { Project } from '@lingx/shared';
interface ProjectCardProps {
project: Project;
}
export function ProjectCard({ project }: ProjectCardProps) {
return (
{project.name}
{project.slug}
);
}
```
## Decision Tree
```
Should I use FSD layer?
Is it a simple page-specific component?
└─ YES → Keep in app/[route]/_components/
Is it used across 3+ pages?
└─ YES → Consider entities/ or features/
Does it have complex internal state?
└─ YES → Consider widgets/
Is it a reusable UI primitive?
└─ YES → Put in shared/ui/
Is it a user action with side effects?
└─ YES → Put in features/
Otherwise → Start in _components/, migrate later
```
## Real-time Collaboration Widget
```
widgets/translation-editor/
├── index.ts # Public API
├── ui/
│ ├── translation-editor.tsx # Main widget
│ ├── presence-bar.tsx # Who's online
│ ├── key-list.tsx # Keys with translations
│ ├── key-row.tsx # Single key
│ └── conflict-dialog.tsx # Conflict resolution
├── model/
│ ├── use-realtime-sync.ts # WebSocket sync
│ ├── use-presence.ts # Presence state
│ ├── use-optimistic-update.ts
│ └── types.ts
└── lib/
└── conflict-resolver.ts # OT/CRDT logic
```
## Anti-Patterns
### ❌ Feature importing widget
```tsx
// BAD - features cannot import widgets
import { TranslationEditor } from '@/widgets/translation-editor';
export function AITranslateFeature() {
return ; // ❌
}
```
### ✅ Widget using feature
```tsx
// GOOD - widgets compose features
import { AITranslateButton } from '@/features/ai-translate';
export function TranslationEditor() {
return (
{/* ✅ */}
);
}
```
### ❌ Entity with side effects
```tsx
// BAD - entities shouldn't have mutations
export function ProjectCard({ project }) {
const { mutate } = useDeleteProject(); // ❌
return (
);
}
```
### ✅ Feature handles action
```tsx
// GOOD - features handle mutations
// features/delete-project/ui/delete-button.tsx
export function DeleteProjectButton({ projectId }) {
const { mutate, isPending } = useDeleteProject();
return ;
}
// entities/project/ui/project-card.tsx
// Pass render prop or slot for actions
export function ProjectCard({ project, actions }) {
return (
{project.name}
{actions}
);
}
```
## Progressive Adoption
1. **Start simple**: New pages use `_components/`
2. **Extract when reused**: Move to entities when used 3+ places
3. **Extract on complexity**: Move to features when adding mutations
4. **Promote to widget**: When combining multiple features with state
5. **Keep shared lean**: Only true primitives (Button, Input, Card)
## Benefits
1. **Clear boundaries** - Each layer has one responsibility
2. **Predictable imports** - Always know where to look
3. **Isolated changes** - Modify one layer without affecting others
4. **Team scalability** - Different teams own different layers
5. **Progressive complexity** - Start simple, scale when needed
Sources:
- [Feature-Sliced Design](https://feature-sliced.design/)
- [Next.js App Router](https://nextjs.org/docs/app)
- [React Server Components](https://www.joshwcomeau.com/react/server-components/)
---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/vinnizp) — claim your Tome and manage your conversions.