Frontend Module Standards

Frontend Module Standards

Apply these rules only to frontend code under src/. Preserve the requested task scope: make touched and newly generated frontend code compliant without performing an unrelated repository-wide migration.

Inspect before editing

1. Identify the owning feature module and its existing barrel, components, hooks, contexts, utilities, state, API usage, and tests.
2. Search for existing shared types, utilities, constants, UI components, hooks, and contexts before adding a new definition.
3. Search for every consumer before moving a definition or changing a module's public exports.
4. Distinguish application-source imports from package imports before applying the @ alias rules.

Use source-root imports

• Treat @ as the alias for src.
• Use @/... imports whenever the import target is frontend application code inside src, including imports within the same feature module.
• Do not use relative paths such as ../, ../../, or ./ for application-source imports.
• Continue using bare package specifiers for external dependencies, such as react or react-router-dom.
• Use import type for every type-only import.

Organize feature modules

• Place every frontend feature in src/modules/<feature>/.
• Use .ts for non-JSX files and .tsx for files containing JSX. Do not add JavaScript feature-module files.
• Give every feature module an index.ts barrel that exposes only its required public API.
• Import another feature module only through that module's index.ts. Never deep-import another module's components, hooks, contexts, modals, utilities, or other implementation details.
• Keep module-private implementation details out of the barrel.
• Do not create view/ directories inside feature modules.
• Keep module-owned UI components within the owning module, either at its root or in clearly named component-specific directories.

A feature module may contain only the directories it needs:

src/modules/<feature>/
|-- index.ts
|-- FeatureComponent.tsx
|-- hooks/
|-- context/
|-- modals/
|-- utils/
`-- tests/

Design exports deliberately

• Export components and other public symbols at their declarations. This does not apply to re-exports from index.ts barrels.
• Do not export speculative helpers, unused symbols, or module-private implementation details.
• For every exported component, add a brief comment at its definition naming the consuming module or modules and explaining why they use it.
• Update an exported component's consumer comment whenever its consumers change.
• Use clear, specific names for functions, variables, components, and hooks.
• Add a concise comment wherever intent, ordering, invariants, or edge cases would otherwise be unclear.

Example:

/** Used by the chat and plugins modules to display the active provider. */
export function ProviderBadge() {
  // ...
}

Use types, not interfaces

• Do not introduce TypeScript interface declarations in frontend code. Use type aliases instead, including for component props, context values, state shapes, and API data.
• When the requested work directly touches an existing interface, convert it to a type when doing so remains within scope.
• Use export type when exporting a type.
• Use import type when importing a type.
• Use type-only barrel exports such as export type { Session }.

Place types by usage

• Define a type directly in its sole owning component or implementation file when only that file uses it.
• When two or more files use the same type, place it in src/shared/types.ts.
• Do not create module-local types.ts files.
• Do not duplicate a shared type to avoid importing it.
• Add a brief comment to every type in src/shared/types.ts explaining what it represents and how it should be used.

Place utilities by usage

• Define a utility directly in its sole owning component or implementation file when only that file uses it.
• When two or more files use the same utility, place it in src/shared/utils.ts.
• Do not create a module-level utils.ts file or duplicate a shared utility to avoid importing it.
• Add a brief comment to every utility in src/shared/utils.ts explaining what it does and how it should be used.
• A large module-private utility may be placed in src/modules/<feature>/utils/ when keeping it in its sole consumer would make that file impractical to maintain.
• Give large module-private utility files descriptive names, such as mobileTerminalSelection.ts; do not name them utils.ts.
• Keep a large utility module-private unless it acquires consumers in other modules. If it becomes shared across multiple modules, move it to src/shared/utils.ts.

Place constants by usage

• Define a constant directly in its sole owning component or implementation file when only that file uses it.
• When two or more files use the same constant, place it in src/shared/constants.ts.
• Do not create module-local constants.ts files or duplicate shared constants.
• Name true constants using UPPER_SNAKE_CASE.
• Treat a value as a constant only when it is fixed independently of runtime evaluation.
• A runtime-derived value such as platform detection is a variable or utility, even if it was previously given an uppercase name. Place it according to the utility rules.
• Add a brief comment to every constant in src/shared/constants.ts explaining what it represents and how it should be used.

Organize shared definitions

Within src/shared/types.ts, src/shared/utils.ts, and src/shared/constants.ts:

• Keep related definitions adjacent.
• Introduce each related group with //----------------- DESCRIPTION OF GROUP ------------.
• Separate unrelated groups with // ---------------------------.
• Document each definition individually, even when it belongs to a documented group.
• Avoid unrelated catch-all groups.