04-code-organization/09-splitting-large-files.md

Splitting large files

Large files are harder for both humans and LLMs to read, reason about, and safely edit. Vroq apps should keep files reasonably small by splitting them along real responsibility boundaries.

When a file is too large

Consider splitting a file when:

it mixes multiple responsibilities (UI + API + state logic)
it becomes difficult to read in one pass
unrelated sections of the file change frequently
multiple contributors or LLM edits touch different areas

There is no strict line-count rule, but if the purpose of the file is no longer obvious, it is probably too large.

How to split safely

Use this workflow:

1. Identify clear responsibilities in the file. 2. Extract one responsibility into a new file (component, section, reducer helper, or API client). 3. Keep the original file as the orchestrator that imports the new pieces. 4. Verify that behavior is unchanged.

Example:

A large feature UI file → extract FileListSection and FileDetailsSection.
UI file with networking → move calls into fileApi.js.

Preferred split targets

Common targets for splitting include:

**Sections** – when a feature UI has multiple visible areas
**Components** – when UI is reusable or purely presentational
**API clients** – when networking logic appears in UI files
**Reducer helpers** – when reducer cases become complex

Avoid over-splitting

Do not create tiny files for trivial helpers that are used only once inside a feature. Over-splitting can make navigation harder.

Prefer splits that improve clarity and ownership.

Final rule

Split files where it makes responsibilities clearer, not simply to reduce line count. The resulting structure should be easier to understand and easier to modify later.