Design Feature-Based React Architecture

---
name: "feature-based-react"
description: "Plan, review, and refactor React or Next.js repositories into feature-oriented modules with explicit boundaries, shared code rules, and scalable imports."
---

# Design Feature-Based React Architecture

Use this skill when creating a React project structure, reviewing module boundaries, or moving an existing codebase toward feature ownership.

## Target model

Organize business behavior by feature. Keep application-wide infrastructure in `core`, genuinely reusable primitives in `shared` when the project needs that layer, and route composition near the framework's routing entry points.

```text
src/
  core/
    api/
    config/
    providers/
  features/
    auth/
      api/
      components/
      hooks/
      model/
      index.ts
    checkout/
      ...
  shared/
    ui/
    lib/
```

Adapt names to the repository; do not impose this tree when an established equivalent already works.

## Workflow

1. Inspect routes, product capabilities, state ownership, API clients, and current import direction.
2. Identify features by business responsibility, not by technical file type.
3. Assign each component, hook, request, and type to the feature that owns its reason to change.
4. Keep cross-cutting infrastructure in `core`; place code in `shared` only after at least two real consumers prove that it is generic.
5. Define a public entry point for each feature and keep internal modules private.
6. Prevent circular dependencies. Features may depend on core/shared layers, but avoid feature-to-feature imports unless the dependency is explicit and stable.
7. Keep route files thin: compose features, load route data, and handle framework metadata there.
8. Migrate incrementally, preserving behavior and validating each moved slice.

## Decision rules

- Co-locate tests, styles, schemas, and feature-specific types with their owner.
- Do not create a global `components`, `hooks`, or `utils` dumping ground.
- Avoid premature abstraction. Duplication can be cheaper than a false shared dependency.
- Prefer domain vocabulary such as `checkout` or `permissions` over generic names such as `common`.
- Expose the smallest public API needed by other modules.

## Review output

Provide:

1. A short map of existing responsibilities.
2. Boundary problems ranked by impact.
3. A proposed tree containing real project names.
4. Allowed import directions.
5. An incremental migration sequence with validation points.

When asked to refactor, preserve public behavior, update imports atomically, and run type checking, tests, linting, and a production build when available.