Directory Structure
This guide helps you organize your app features consistently. Every feature should follow this structure for maintainable and scalable development.
Core Structure
api/
components/
(routes)/
api/
→ All API concerns (hooks, services, types, models)components/
→ UI components (ui/, views/, forms/)(routes)/
→ Next.js pages (page.tsx, layout.tsx files only)
Optional Structure (Create As Needed)
contexts/
hooks/
lib/
types/
contexts/
→ React contextshooks/
→ Custom React hookslib/
→ Utilities and constants (when substantial)types/
→ Frontend types (when separate from API types)
File Placement Decision Tree
When creating a new file, ask yourself these questions in order:
- API-related? →
api/
(always create this folder) - UI Component? →
components/
(always create this folder) - Next.js page? →
(routes)/
(always create this folder) - React context? →
contexts/
- Custom hook? →
hooks/
- Utility function? →
lib/
(create if utilities are substantial) - Frontend type? →
types/
(create if types are complex)
API Directory Structure
api/ ├── hooks/ → TanStack Query hooks, data fetching ├── services/ → Raw API functions, HTTP clients ├── types/ → API response types, request payloads └── models/ → Data transformation, factory functions
Components Directory Structure
components/ ├── views/ → Page-level components, main views ├── ui/ → Reusable UI components, design system └── forms/ → Form components, input controls
Structure Examples
✅ Full Feature Structure
contacts/ ├── api/ │ ├── hooks/ │ │ ├── useContacts.ts │ │ ├── useCreateContact.ts │ │ └── useUpdateContact.ts │ ├── services/ │ │ └── contactsApi.ts │ ├── types/ │ │ └── index.ts │ └── models/ │ └── ContactModel.ts ├── components/ │ ├── views/ │ │ └── ContactsView.tsx │ ├── ui/ │ │ ├── ContactCard.tsx │ │ └── ContactList.tsx │ └── forms/ │ └── ContactForm.tsx ├── contexts/ │ └── ContactsContext/ │ ├── Context.ts │ ├── Provider.tsx │ └── useContactsContext.ts ├── hooks/ │ ├── useContactFilter.ts │ └── useContactSearch.ts └── (routes)/ ├── page.tsx └── [contactId]/ └── page.tsx
⚠️ Minimal Structure (Also Acceptable)
simple-feature/ ├── api/ │ └── simpleApi.ts ├── components/ │ └── SimpleView.tsx └── (routes)/ └── page.tsx
💡 Best Practices
- Start simple - only create folders when you need them
- Don't create empty directories just to follow the structure
- Group related functionality together within each directory
- Use consistent naming conventions across your features
- Consider the maintenance burden - simpler is often better
This structure adapts to your feature's complexity while maintaining consistency across your application. Focus on making your code easy to find and understand rather than following every guideline perfectly.