Feature-Based Frontend

A practical guide to structuring Next.js/React applications using feature-based architecture with layered data flow (app, features, domains, core).

Contents

This repo contains two artifacts:

AI Agent Skill

An installable skill for Cursor and OpenAI Codex agents that guides code generation to follow feature-based architecture patterns.

Location: skills/feature-based-frontend/

What it does:

• Enforces 4-layer import rules (app → features → domains → core)
• Provides checklists for adding new domains (5 steps) and features (4 steps)
• Guides server vs client component decisions
• Ensures proper data fetching patterns (thin domain hooks + rich feature hooks)

Medium Article

medium.com/@srachel27/feature-based-architecture-for-next-js-scaling-react-apps-with-layered-design-216b2f9fa9e2

---

Installing the Skill

Cursor

Copy or symlink the skill folder to your Cursor skills directory:

# Personal skill (available in all projects)
cp -r skills/feature-based-frontend ~/.cursor/skills/

# Or project-level skill (shared via repo)
cp -r skills/feature-based-frontend .cursor/skills/

Then invoke with: Use $feature-based-frontend to add a new frontend domain and feature with proper layer boundaries.

OpenAI Codex

The skill includes agents/openai.yaml for Codex compatibility. Place the skill folder where your Codex agent can discover it.

---

Skill Structure

skills/feature-based-frontend/
├── SKILL.md              # Main instructions (procedural, < 500 lines)
├── agents/
│   └── openai.yaml      # Codex agent interface metadata
└── references/
    ├── layer-rules.md        # Import boundaries and enforcement
    ├── domains-layer.md      # API, types, mappers, thin hooks
    ├── features-layer.md     # Components, hooks, stores, shared
    └── testing.md            # Vitest, component tests, hook tests

---

Key Patterns Covered

1. Four-Layer Architecture -- app, features, domains, core with strict import direction
2. Feature Isolation -- independent UI modules that never cross-import
3. Thin Domain Hooks -- useQuery/useMutation wrappers with no business logic
4. Rich Feature Hooks -- compose domain hooks with UI state and business logic
5. Server-First Components -- default to Server Components, add "use client" only when needed
6. Layer Testing -- each layer mocks the layer below it

---

License

MIT