Sota Structure

SOTA Structure

File/folder structure doctrine for TypeScript projects and monorepos, distilled from the 2025/2026 consensus (bulletproof-react, TkDodo, Kent C. Dodds, Turborepo, Hono, and the real source of the vercel/shadcn/astro/changesets CLIs), plus the audit procedure that enforces it. All numbers and citations: references/evidence.md.

A repo's own contract (AGENTS.md / CLAUDE.md) overrides this skill — but when the contract conflicts with measured evidence, flag the conflict instead of silently following either side.

Core Model

1. Vertical slices over horizontal layers. Organize by feature/domain. Technical-type dirs (components/, hooks/, services/) are allowed only inside a slice, in the shared tier, or in tiny apps.
2. Unidirectional imports: shared → features → app. Features never import each other; code promotes to shared on its second consumer (rule of two). The rule only exists if machine-enforced.
3. Colocate first, extract later. Code lives as close as possible to where it is used.
4. The folder carries context; the file carries the concept. Never repeat a path segment in the basename.
5. Barrels only at real package boundaries.
6. A test lives next to what it tests.

Monorepo Layout

• apps/ + custom top-level groups (cli/, libs/, tooling/) are all first-class — Turborepo/pnpm discover workspaces via globs, and vercel/turborepo itself uses custom groups. Never nest workspaces.
• Public CLI binaries: unscoped + branded (turbo, vitest, shadcn). Libraries and secondary CLIs: one consistent branded scope with agnostic leaf names (@scope/core, @scope/add). Nobody ships an @acme-style placeholder scope.
• Internal packages: compiled + publishable when any handoff/copy/declaration contract exists; just-in-time source exports only when every consumer transpiles.

Per-Surface Taxonomy

Principles above apply everywhere; the bulletproof-react dir taxonomy applies to UI surfaces only.

Embedded server inside a CLI: the command is a thin launcher adapter; the server is its own module or workspace (astro/vercel pattern).

Naming

• kebab-case for all files and folders; PascalCase/camelCase only for exported symbols. (TanStack core and vitest use camelCase files — a per-repo tradition; never mix conventions within one repo.)
• Basename = the file's primary export, kebab-cased. Ban grab-bags: utils.ts, helpers.ts, common.ts, misc.ts, shared.ts.
• No hard hyphen cap exists anywhere — linters cap case, never length. But elite repos sit at 82–99% of files with ≤1 hyphen (vercel CLI: 18% with 2+; bulletproof-react: 0%). The mechanism is the folder-context move, not abbreviation:
  • features/review/hooks/use-review-results-keyboard.ts → use-results-keyboard.ts — the path already says review.
  • 2+ hyphens in a basename = shorten-via-context candidate; 3+ = split/rename smell.
• Path-echo is redundancy, not description. A basename repeating a path segment is a finding. "The name reads fine standalone" is not a defense — files are read at their path.
• Exempt from hyphen counting: the use- hook prefix, the <component>-<part> compound idiom (menu-item.tsx), and tooling dot-suffixes.
• Dots only for tooling-known suffixes (.test, .spec, .e2e, .stories, .config, .d); hyphens separate words. Angular v20 dropped its .component/.service dot-types for dash-style names to converge with the React/TS ecosystem.
• Dot-segments are not word separators. review.routes.ts, user.service.ts, foo.command.ts (NestJS style) are findings. Apply the folder-context move instead: flat routes/review.ts, or at 3+ files a routes/review/ folder containing route.ts, schema.ts, stream.ts. Inside a unit folder, files drop the unit name entirely: commands/review/command.ts + handler.ts, never review.command.ts.

Barrels — Verdict Table

Measured cost of internal barrels: TkDodo −68% modules (11k→3.5k); Vitest −85% transformed files; Atlassian −75% CI build minutes; Vercel −28% builds, up to −40% cold starts. bulletproof-react removed its own barrels and now recommends importing files directly.

Folders, Grouping, Colocation

• Default: flat siblings — button.tsx + button.test.tsx next to each other.
• A unit gets its own folder at 3+ files. A folder never gets an index.ts just because it exists.
• Tests: colocated <name>.test.ts(x); integration as <name>.integration.test.ts; e2e per app under tests/e2e/*.e2e.ts; never __tests__/, never a parallel unit-test tree.
• Stories/docs files colocate the same way; the build must exclude them from dist and registry/copy output.

File Size & Splitting

• Target ≤200 lines, warn >300, hard review >350 — counted per responsibility, not mechanically. Generated/data files exempt.
• One main export per file + its small private helpers. Extract helpers only on proven reuse.
• Do NOT split cohesive sequential code — pipelines, state machines, protocol seams (Locality of Behaviour / Carmack's inlining argument). A cohesive 350-line state machine beats five fragments that force frame-switching.
• Orchestrator split: when a file genuinely splits, the original filename stays as the orchestrator re-exporting the unchanged public surface; the parts become siblings. Public imports never break.

Decision Guide

"Where does this code go?"

1. Used by one feature → that feature's folder, named without the feature prefix.
2. Needed by a second feature in the same app → app-shared tier (hooks/, components/, lib/).
3. Needed by a second app/package AND generic outside the product → extract to the owning lib (rule of two, real named concept, clearer call sites).
4. Product-specific composition, copy, domain flows → stays in the app forever.

"Folder or file?" → file, until 3+ siblings. "Barrel?" → only at a package boundary. "Split?" → only at 2+ responsibilities, not at a line count alone.

Enforcement — Wire It, Don't Prose It

• dependency-cruiser: layer boundaries, no-circular, no-orphans
• knip: dead files, exports, dependencies
• Biome / eslint-plugin-unicorn filename-case: kebab-case
• lint bans: internal barrels; self-package barrel imports; deep imports bypassing another package's public exports

Structural Refactor Protocol (mass moves/renames)

1. Pure-move commit first — moves/renames with ZERO logic edits, so git rename detection survives and review shows renames, not delete+add. Splits and logic changes go in stacked commits after.
2. Codemod with ts-morph for cross-package moves — IDE import-update is unreliable across package boundaries (TypeScript #59136, closed not-planned).
3. Lockstep handoff rule: a rename touching a published/copy surface updates source, registry JSON, generated bundles, docs, examples, and consumers atomically in one PR.
4. Pre-1.0 is the cheap window. Every rename after first publish is a breaking contract change.
5. Gates between phases: full type-check (project refs make boundary breakage a hard error) → FULL test suite (not affected-only) → artifact/registry validation → smoke/e2e → git diff --check.

Audit Procedure

When auditing structure against this bar:

1. Measure (exclude generated code): hyphen distribution per basename; file-size buckets (>200/>300/>350); barrel census (public entry vs internal re-export); test placement patterns; grab-bag basenames; path-echo names; boundary violations (cross-feature imports, shared→app); mirrored/duplicated trees.
2. Every finding needs file:line evidence and a concrete fix (exact target name/path).
3. Spec fixes in this phase order: pure moves/renames → DRY/extractions → barrel dissolution → splits & local fixes → enforcement wiring → docs. Gates between phases per the protocol above.

Rationalizations — Counters