Frontend Folder Structure

Last updated:

Folder structure affects maintainability and onboarding — structure should reflect system organisation clearly.

01 — Purpose

Structure shapes onboarding and maintenance

Folder structure affects maintainability and onboarding significantly — structure should reflect system organisation clearly.

New contributors should guess where a file lives before searching. Predictable folders — components, layouts, styles, pages — reduce cognitive load and review time.

Align with CSS architecture (LSCSS layers), JS module architecture, and this site’s src/ layout as a reference.

02 — Principles

Organisation you can explain in one sentence

Predictable naming, clear separation of concerns, modular organisation.

  • predictable naming — two-word components, feature folders, no cryptic abbreviations
  • clear separation — UI, data, styles, and config do not share one junk drawer
  • modular organisation — features or responsibilities grouped, not only file type
  • feature or responsibility grouping — components/patterns/ vs dumping everything in misc

03 — Practice

Example areas

Common folders and what belongs in each.

  • components — reusable UI and content blocks; co-locate small scripts when tied to one component
  • layouts — page shells, shared chrome
  • pages or routes — thin files that compose layouts and content
  • styles — LSCSS layers: settings, base, utilities, components, theme — see cascade layers
  • data or lib — tokens, nav config, shared helpers — not business logic hidden in components
  • scripts — build, CI, one-off tooling

Scalability

Structure should support onboarding, maintainable growth, and shared standards — split folders before files exceed what someone can understand in one sitting (see LSCSS architecture on file size).

04 — Avoid

Structure that confuses

Structure should reduce cognitive load — not increase it.

  • giant unstructured directories — hundreds of files flat in components
  • unclear ownership — nobody knows who maintains shared/
  • duplicated logic — same helper in three “utils” folders
  • arbitrary nesting — features/foo/components/partials/v2/ with no documented rule

05 — Close

Document the map

New contributors should find the README or architecture page that explains your tree.

When you add a top-level folder, document what goes there and what does not. Review PRs that introduce new roots — structure drift is hard to undo.

See frontend governance, frontend documentation standards, and CSS standard.