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