08-recipes/09-split-a-feature-cleanly.md

Split a feature cleanly

Split a feature cleanly

Use this recipe when a feature has grown too large and needs clearer internal boundaries.

The goal is to split the feature without breaking ownership or scattering logic across the project.

Steps

1. Identify the responsibilities inside the feature. 2. Separate UI fragments into **sections**. 3. Extract reusable UI into **components**. 4. Move remote calls into a **feature API client**. 5. Keep state transitions inside the **feature reducer**. 6. Keep actions in the **feature actions file**. 7. Leave the top feature file as the **orchestrator**.

Typical structure after split

features/featureName/
  index.js
  featureReducer.js
  featureActions.js
  FeatureSection.js
  apiClient.js
  sections/
  components/

Rules

• keep all feature logic inside the feature folder
• avoid creating cross-feature dependencies unless code is clearly shared
• keep the reducer responsible for state transitions
• keep UI files focused on rendering and events

What to avoid

Do not split a feature by scattering files across unrelated directories.

Do not move feature-specific logic into shared/ unless it is reused by multiple features.

Final rule

A split feature should be easier to understand than the original file, while preserving clear ownership of state, UI, and API behavior.