Axon 911 Frontend DocsAxon 911 Frontend Docs
Axon 911 Frontend Docs
    Loading navigation…
U
User
Switch to light mode
  1. Architecture
  3. File Organization

File Organization

File structure, barrel files, and size limits.

Quick Reference
File size limits:
  • React components: Max 500 lines
  • Hooks: Max 200 lines
  • Utilities: Max 200 lines
File organization:
  • No barrel files in apps (direct imports only)
  • GraphQL files co-located with components
  • Hooks co-located with components
  • Named exports (prefer over default)
No Barrel Files in Apps
Don't use barrel files (index.ts that re-exports) in applications:
Why:
  • Barrel files bundle unused code
  • Tree-shaking less effective
  • Longer build times
Exception: Barrel files OK in packages (@prepared911/ui) where consumers import from package root.
File Size Limits
React Components (Max 500 lines)
Hooks (Max 200 lines)
Feature Folder Structure
GraphQL Co-location
GraphQL files MUST be co-located with the component/hook that uses them:
Name each file for the kind of definition it holds: queries.graphql, mutations.graphql, subscriptions.graphql, or fragments.graphql. The page or root that owns a request keeps the queries.graphql. Each component below it keeps a fragments.graphql with its Component_prop fragment. See GraphQL Colocation and GraphQL Fragments.
Module Structure
For larger features:
Named Exports
Prefer named exports over default exports:
Benefits:
  • Better IDE autocomplete
  • Easier refactoring
  • Consistent naming across codebase
  • Better tree-shaking
When to Split Files
Split when:
  • File exceeds size limit (500 for components, 200 for hooks)
  • Multiple concerns in one file
  • Sub-components can be reused
  • Logic can be tested independently
Extract to:
  • Custom hooks (use-*.ts)
  • Sub-components (ComponentName.tsx)
  • Utilities (helpers.ts, formatters.ts)
  • Types (types.ts, models.ts)
Directory Naming
Use kebab-case for directories:
Use PascalCase or kebab-case for files:
OR
Be consistent within a feature/module.
Co-location Principles
Co-locate related files:
  • GraphQL with components that use them
  • Hooks with components that use them
  • Styles with components
  • Types with components (when not shared)
Shared files:
  • Types used across features → models/ or types/
  • Utilities used across features → utils/
  • Hooks used across features → hooks/
Related Documentation
  • Component Patterns - Component organization
  • Writing Hooks - Custom hooks
Reference Files
For more detailed technical guidance, see these reference files:
  • arch-barrel-files.md
  • arch-file-size-limits.md
  • component-file-organization.md
Previous
Code quality / Refactoring Guide
Next
Architecture / Data Fetching
On this page
Quick Reference
No Barrel Files in Apps
File Size Limits
React Components (Max 500 lines)
Hooks (Max 200 lines)
Feature Folder Structure
GraphQL Co-location
Module Structure
Named Exports
When to Split Files
Directory Naming
Co-location Principles
Related Documentation
Reference Files