frontend-dev-guidelines

Frontend Dev Guidelines - React TypeScript Development Standards

Skills Overview

Frontend Dev Guidelines is a set of frontend development standards for modern React + TypeScript applications, helping teams build scalable, predictable, maintainable production-ready code.

Applicable Scenarios

Creating New React Components or Pages

Provides standardized component templates and code structure ordering to ensure new code complies with team standards from the start.

Refactoring or Reviewing Existing Code

Evaluates code quality with FFCI (Frontend Feasibility & Complexity Index) to identify complex components that should be simplified.

Team Collaboration and Code Consistency

Unifies core practices such as data fetching, routing configuration, and styling, reducing code style differences across the team.

Core Requirements

Prefer Suspense for Data Fetching

Use useSuspenseQuery as the primary data fetching method. Disable manual isLoading checks and loading-state early returns, so Suspense boundaries handle loading states uniformly.

Feature-Driven Code Organization

Domain logic must be placed in the features/ directory. Reusable components belong in the components/ directory. Cross-feature coupling is prohibited. Keep code boundaries clear.

Strict TypeScript Discipline

Disallow the any type, require explicit return types, and use import type to import types. Treat types as first-class design artifacts.

Common Questions

What is FFCI, and how do I use it?

FFCI (Frontend Feasibility & Complexity Index) is the frontend feasibility complexity index used to assess the value of implementing a component or feature. The calculation formula is:
(Architectural Fit + Reusability + Performance) − (Complexity + Maintenance Cost)
The score range is from -5 to +15. Scores of 10–15 can be implemented directly; 6–9 should be handled cautiously; ≤2 requires redesign.

Why is isLoading prohibited?

The traditional isLoading pattern leads to many conditional checks and early returns inside components, increasing code complexity. Using Suspense separates loading-state handling from component logic. Suspense boundaries manage loading states uniformly, allowing components to focus on rendering logic and improving readability and maintainability.

In what order should component code be organized?

Recommended order: 1) Types/Props definitions → 2) Hooks → 3) Derived values (useMemo) → 4) Event handlers (useCallback) → 5) Rendering logic → 6) Default export. This order matches the direction of data flow, making the code easier to read and understand.