Build Feature Structure

Overview

Use this skill to reorganize code around features or scaffold a new feature without embedding business logic. Treat a feature as a composition boundary, not just a place to move one large smart component. Infer the local pattern first, preserve established repository naming and wiring when they already exist, and keep changes minimal-diff unless the user asks for broader restructuring.

A feature file should compose child features and leaf UI directly. Do not default to one large screen-shaped UI component that receives the whole feature state and callback surface as props. Features may import other features. UI is not a dumping ground for screen orchestration.

Layer Roles and Import Boundaries

When normalizing or creating a feature-based structure, prefer at most four library types: data-access, feature or feature-<app>, ui or ui-<app>, and optional util. If the repository already uses names such as features/ for folders, keep the naming and apply the same responsibilities.

• data-access: own adapters, fetching, invalidation, mutations, mutation-side effects, persistence, platform checks, and other side-effectful integration work. It may import from other data-access modules. It must not import feature or ui. Prefer one exported thing per file, one hook per file when hooks are used, one query or mutation per hook when possible, and concrete imports over barrels unless the repository already standardizes a different pattern. Mutation hooks should own error handling, invalidation, and side effects.
• feature or feature-<app>: act as the smart or orchestration layer. It should own routed screen logic and route params, decide which data-access calls run, compose child features when a workflow or screen subsection has distinct phases, prerequisites, or hook orchestration, and pass only minimal resolved data or imperative domain actions into ui. In file-based routing repos, framework-owned route files stay as thin wrappers outside the feature tree. It may import from data-access, ui, and narrower feature files.
• ui or ui-<app>: stay presentational or dumb. It may import from other ui modules and passive pieces from data-access, such as pure helpers or types, but it must not own route parsing, API calls, mutations, or other side-effectful workflow orchestration. Prefer granular leaf components over a single large screen component when feature is orchestrating multiple states or workflows. Keep ephemeral form or input state local to the leaf UI component unless multiple siblings genuinely need it. Do not turn ui into a screen-shaped prop bag sink.
• util: stay optional and rare. Use it for pure helpers, usually on the backend, and keep it free of rendering, route handling, and side-effectful orchestration.

File Shape Defaults