home / skills / pproenca / dot-skills / feature-arch

feature-arch skill

needs review

This skill helps you enforce feature-based React architecture to improve project structure, code organization, and cross-feature boundaries across the codebase.

npx playbooks add skill pproenca/dot-skills --skill feature-arch

Review the files below or copy the command above to add this skill to your agents.

Files (48)

SKILL.md

5.1 KB

---
name: feature-arch
description: React feature-based architecture guidelines for scalable applications (formerly feature-architecture). This skill should be used when writing, reviewing, or refactoring React code to ensure proper feature organization. Triggers on tasks involving project structure, feature organization, module boundaries, cross-feature imports, data fetching patterns, or component composition.
---

# Feature-Based Architecture Best Practices

Comprehensive architecture guide for organizing React applications by features, enabling scalable development with independent teams. Contains 42 rules across 8 categories, prioritized by impact from critical (directory structure, imports) to incremental (naming conventions).

## When to Apply

Reference these guidelines when:
- Creating new features or modules
- Organizing project directory structure
- Setting up import rules and boundaries
- Implementing data fetching patterns
- Composing components from multiple features
- Reviewing code for architecture violations

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Directory Structure | CRITICAL | `struct-` |
| 2 | Import & Dependencies | CRITICAL | `import-` |
| 3 | Module Boundaries | HIGH | `bound-` |
| 4 | Data Fetching | HIGH | `fquery-` |
| 5 | Component Organization | MEDIUM-HIGH | `fcomp-` |
| 6 | State Management | MEDIUM | `fstate-` |
| 7 | Testing Strategy | MEDIUM | `test-` |
| 8 | Naming Conventions | LOW | `name-` |

## Quick Reference

### 1. Directory Structure (CRITICAL)

- `struct-feature-folders` - Organize by feature, not technical type
- `struct-feature-self-contained` - Make features self-contained
- `struct-shared-layer` - Use shared layer for truly generic code only
- `struct-flat-hierarchy` - Keep directory hierarchy flat
- `struct-optional-segments` - Include only necessary segments
- `struct-app-layer` - Separate app layer from features

### 2. Import & Dependencies (CRITICAL)

- `import-unidirectional-flow` - Enforce unidirectional import flow
- `import-no-cross-feature` - Prohibit cross-feature imports
- `import-public-api` - Export through public API only
- `import-avoid-barrel-files` - Avoid deep barrel file re-exports
- `import-path-aliases` - Use consistent path aliases
- `import-type-only` - Use type-only imports for types

### 3. Module Boundaries (HIGH)

- `bound-feature-isolation` - Enforce feature isolation
- `bound-interface-contracts` - Define explicit interface contracts
- `bound-feature-scoped-routing` - Scope routing to feature concerns
- `bound-minimize-shared-state` - Minimize shared state between features
- `bound-event-based-communication` - Use events for cross-feature communication
- `bound-feature-size` - Keep features appropriately sized

### 4. Data Fetching (HIGH)

- `fquery-single-responsibility` - Keep query functions single-purpose
- `fquery-colocate-with-feature` - Colocate data fetching with features
- `fquery-parallel-fetching` - Fetch independent data in parallel
- `fquery-avoid-n-plus-one` - Avoid N+1 query patterns
- `fquery-feature-scoped-keys` - Use feature-scoped query keys
- `fquery-server-component-fetching` - Fetch at server component level

### 5. Component Organization (MEDIUM-HIGH)

- `fcomp-single-responsibility` - Apply single responsibility to components
- `fcomp-composition-over-props` - Prefer composition over prop drilling
- `fcomp-container-presentational` - Separate container and presentational concerns
- `fcomp-props-as-data-boundary` - Use props as feature boundaries
- `fcomp-colocate-styles` - Colocate styles with components
- `fcomp-error-boundaries` - Use feature-level error boundaries

### 6. State Management (MEDIUM)

- `fstate-feature-scoped-stores` - Scope state stores to features
- `fstate-server-state-separation` - Separate server state from client state
- `fstate-lift-minimally` - Lift state only as high as necessary
- `fstate-context-sparingly` - Use context sparingly for feature state
- `fstate-reset-on-unmount` - Reset feature state on unmount

### 7. Testing Strategy (MEDIUM)

- `test-colocate-with-feature` - Colocate tests with features
- `test-feature-isolation` - Test features in isolation
- `test-shared-utilities` - Create feature-specific test utilities
- `test-integration-at-app-layer` - Write integration tests at app layer

### 8. Naming Conventions (LOW)

- `name-feature-naming` - Use domain-driven feature names
- `name-file-conventions` - Use consistent file naming conventions
- `name-descriptive-exports` - Use descriptive export names

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules
- Individual rules: `references/{prefix}-{slug}.md`

## Related Skills

- For feature planning, see `feature-spec` skill
- For data fetching, see `tanstack-query` skill
- For React component patterns, see `react-19` skill

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

Overview

This skill provides concise, practical guidelines for organizing React applications by feature to improve scalability, team independence, and maintainability. It codifies priorities across directory structure, imports, module boundaries, data fetching, component composition, state, testing, and naming. Use it during development, reviews, and refactors to enforce clear boundaries and predictable patterns. The guidance is prioritized so teams can tackle high-impact rules first.

How this skill works

The skill inspects tasks related to project structure, imports, module boundaries, data fetching, and component composition and recommends specific rules and patterns. It highlights critical rules (directory layout and import boundaries) first, then high- and medium-impact practices like module isolation, colocated queries, and component separation. It maps problems to concrete remedies (e.g., move code into feature folders, expose public APIs, avoid cross-feature imports). The output is actionable: directory layout suggestions, import rules, state-scoping advice, and testing placement.

When to use it

When creating a new feature or module to decide folder layout and public API
When reviewing code to catch cross-feature imports or boundary violations
When refactoring monolithic folders into feature-scoped units
When designing data fetching patterns and query placement
When composing components across features to avoid prop drilling and shared state

Best practices

Organize by feature, not by technical type; keep features self-contained
Enforce unidirectional imports and forbid cross-feature direct imports
Expose functionality via a feature public API and avoid deep barrel re-exports
Colocate data fetching and queries with the feature; use feature-scoped query keys
Keep components single-responsibility and prefer composition over prop drilling
Scope state to features, separate server vs client state, and reset on unmount

Example use cases

Refactor a large components/containers tree into feature folders with public index exports
Audit imports to replace cross-feature references with event-based communication or public APIs
Design data fetching: colocate queries in the feature and fetch on server components when appropriate
Split a shared store into feature-scoped stores to reduce coupling
Place integration tests at the app layer while keeping unit tests next to feature code

FAQ

How strict should import boundaries be?

Treat import boundaries as critical: forbid direct cross-feature imports. Always use the feature's public API or an event-based bridge to keep features decoupled.

When should shared code live in a shared layer?

Only move truly generic utilities to a shared layer. If code is domain-specific, keep it inside the owning feature to avoid coupling and accidental cross-feature dependencies.